claude-code-arcane 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# [2.5.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.4.0...v2.5.0) (2026-08-13)
+
+
+### Features
+
+* **install:** interactive wizard with stack auto-detection ([ae0b9b8](https://github.com/SebastianLuser/claude-code-arcane/commit/ae0b9b8a67146faa22258f30c9d33bf7e4fffbf9))
+* **profiles:** replace base/addon split with thematic categories ([5bcddab](https://github.com/SebastianLuser/claude-code-arcane/commit/5bcddab2e9081e6d6505ac00b6345dd3b57eed4a))
+
+# [2.4.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.3.0...v2.4.0) (2026-08-13)
+
+
+### Bug Fixes
+
+* **agents:** add the three ue-* sub-specialists unreal-specialist delegates to ([9b52708](https://github.com/SebastianLuser/claude-code-arcane/commit/9b527081c9d7166a96a299c2658a1b0adfb4db58))
+
+
+### Features
+
+* **hooks:** detect Unreal projects on session start ([dfb66ae](https://github.com/SebastianLuser/claude-code-arcane/commit/dfb66ae6b70f40dda226f18027aefe574005a5d8))
+* **install-mcp:** handle Unreal's engine-provided MCP alongside Unity ([96fe518](https://github.com/SebastianLuser/claude-code-arcane/commit/96fe51817015d69d31aebc84088c774c9a55dd0b))
+* **unreal:** add the unreal-dev profile with 29 ue-* skills ([011a3f1](https://github.com/SebastianLuser/claude-code-arcane/commit/011a3f1992f1ac515acf9595cfc568f2824a6d21))
+* **unreal:** add ue-naming-conventions from the Gamemakin style guide ([301880e](https://github.com/SebastianLuser/claude-code-arcane/commit/301880e25c8ebd71987e96387fbf74650d313574))
+
 # [2.3.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.2.0...v2.3.0) (2026-08-12)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **397 skills, 106 agents, 16 hooks and 27 rules for Claude Code — selective deploy by profile.**
+> **427 skills, 109 agents, 17 hooks and 28 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 
@@ -32,7 +32,7 @@ Each profile is a YAML file that bundles skills, agents, rules, and permissions:
 ```yaml
 # profiles/backend-ts.yaml
 name: backend-ts
-type: base
+category: backend
 skills: [api-design, auth-strategy, jwt-strategy, ...]
 rules:
   universal: [backend-code, api-code, migration-code]
@@ -43,14 +43,16 @@ permissions:
 
 ### 2. Combine profiles with `+`
 
+All profiles are equal — there is no "base vs addon" distinction. Combine as many as you need:
+
 ```bash
 npx claude-code-arcane install backend-ts+agile+testing
-#                  ^^^^^^^^^^  ^^^^^  ^^^^^^^
-#                  base        addon  addon
 ```
 
 The installer merges all profiles, deduplicates skills, and installs only what's needed.
 
+Not sure what to pick? Run `install` with no arguments to get an interactive picker: it detects your stack (Unity, Unreal, Flutter, Go, NestJS, Next.js, React Native, React, .NET, native Android/iOS...) and pre-selects the matching profiles, then lets you add more from a menu grouped by category. Power users can accept the detected suggestion with a single Enter — or skip the menu entirely with the `a+b+c` syntax above.
+
 ### 3. Core is always included
 
 Every installation automatically loads `core.yaml` first:
@@ -92,7 +94,7 @@ npx claude-code-arcane install unity-dev --dry-run   # Preview without installin
 ```bash
 npx claude-code-arcane add api-design                # Add a single skill
 npx claude-code-arcane add security-audit owasp      # Add multiple skills
-npx claude-code-arcane add +security                 # Add an entire profile as addon
+npx claude-code-arcane add +security                 # Add an entire profile
 npx claude-code-arcane add +database +testing        # Add multiple profiles
 ```
 
@@ -157,48 +159,89 @@ Once installed, manage the installation from within a Claude Code session:
 
 ## Available Profiles
 
-### Base (pick one or combine several)
+All profiles combine freely with `+` — there is no required "base". Grouped by category:
+
+### Backend
 
 | Profile | Stack | Skills | Agents |
 |---------|-------|--------|--------|
-| `unity-dev` | Unity programmer — C#, architecture, performance, builds | 25 | game |
-| `unity-design` | Game designer — GDDs, balance, art bible, playtesting | 17 | game |
-| `audio` | Game audio — direction, composition, sound design, middleware, VO, QA | 13 | audio |
 | `backend-ts` | Backend TypeScript — Fastify, Prisma, Zod, API design | 33 | engineering |
 | `backend-go` | Backend Go — Clean Arch, DB, auth, API, CI | 19 | engineering |
 | `backend-dotnet` | Backend .NET — ASP.NET Core, Vertical Slice/Clean, EF Core, JWT | 25 | engineering |
+| `backend-nestjs` | Backend NestJS — feature modules, DI, Prisma, JWT, microservices | 25 | engineering |
+| `backend-nextjs` | Next.js full-stack — App Router, RSC, Server Actions, SEO, AI SDK | 22 | engineering |
+
+### Frontend & Design
+
+| Profile | Stack | Skills | Agents |
+|---------|-------|--------|--------|
 | `frontend` | React + Vite + TypeScript | 14 | engineering |
+| `design` | Figma, UX review, design system, handoff | 6 | product |
+
+### Mobile
+
+| Profile | Stack | Skills | Agents |
+|---------|-------|--------|--------|
 | `mobile` | React Native + Expo + TypeScript | 12 | engineering |
 | `flutter` | Flutter + Dart cross-platform | 8 | engineering |
 | `android-native` | Kotlin + Jetpack Compose + Material Design 3 | 8 | engineering |
 | `ios-native` | Swift + UIKit/SwiftUI + Apple HIG | 8 | engineering |
 
-### Add-ons (combine with `+`)
-
-| Add-on | Adds | Skills | Agents |
-|--------|------|--------|--------|
-| `+agile` | Sprints, standups, retros, estimates | 10 | management, product |
-| `+docs` | PDF, PPTX, XLSX, DOCX, architecture decisions | 8 | — |
-| `+testing` | Contract, performance, regression, flakiness | 11 | quality |
-| `+infra` | Terraform, observability, secrets, rollback, K8s | 17 | devops |
-| `+database` | Indexing, migrations, seeding, replicas, optimization | 8 | — |
-| `+security` | Audits, OWASP, secrets, backups | 5 | — |
-| `+design` | Figma, UX review, design system, handoff | 6 | product |
-| `+integrations` | GitHub Projects, Slack, Postman | 3 | integrations |
-| `+clickup` | ClickUp via MCP — tasks, docs, time tracking | 3 | — |
-| `+jira` | Jira via REST API — issues, sprints, boards | 3 | — |
-| `+ai` | LLM cost optimization, RAG, ML, data engineering | 7 | ai |
-| `+business` | Contracts, customer success, revenue ops, sales | 4 | business |
-| `+clevel` | C-suite advisors, board prep, strategic ops | 28 | clevel |
-| `+finance` | Investment analysis, financial modeling, SaaS metrics | 3 | business |
-| `+marketing` | Content, growth, SEO/CRO, strategy, analytics | 44 | marketing |
-| `+regulatory` | ISO 13485, GDPR, FDA, SOC 2, ISMS, QMS, MDR | 13 | regulatory |
-| `+job-hunt` | Job search end-to-end — master profile, ATS CV with verification, job scraping with dedup, LinkedIn, portfolio, cover letters, outreach, interview prep, registry/CSV traceability, fresh-context review agents | 17 | career |
-| `+freelance` | Freelance projects — keyless public-source scanning with dedup, market rate intel, client risk screening, proposals priced above your net floor rate, contracts/SOWs, registry/CSV traceability, kickoff scope validation, delivery and change orders, acquisition-cost pipeline | 15 | freelance |
-| `+ecommerce` | Commerce end-to-end agnóstico de lenguaje — data model, checkout, inventario, órdenes, pagos, promociones, shipping/tax, listings, analytics, feeds, storefront, suscripciones | 12 | ecommerce |
-| `+second-brain` | Second brain en Obsidian — captura sin fricción, reviews diario/semanal/mensual, notas atómicas y hub files (PARA + Zettelkasten), búsqueda con ranking, caché de contexto entre sesiones, auditoría de salud del vault, sintaxis nativa (markdown, Bases, Canvas) | 14 | — |
-| `+self-improving` | Agent self-improvement and skill extraction | 2 | — |
-| `+statusline` | Claude Code status bar (branch, division, session info) | 0 | — |
+### Gamedev
+
+| Profile | Stack | Skills | Agents |
+|---------|-------|--------|--------|
+| `unity-dev` | Unity programmer — C#, architecture, performance, builds | 25 | game |
+| `unity-design` | Game designer — GDDs, balance, art bible, playtesting | 17 | game |
+| `unreal-dev` | Unreal Engine 5 programmer — C++, Blueprints, GAS, replication, rendering, packaging | 49 | game |
+| `visual-novel` | Visual novel developer — Ren'Py, narrative, branching | 17 | visualnovel, game |
+| `audio` | Game audio — direction, composition, sound design, middleware, VO, QA | 13 | audio |
+
+### Platform & Quality
+
+| Profile | Adds | Skills | Agents |
+|---------|------|--------|--------|
+| `infra` | Terraform, observability, secrets, rollback, K8s | 17 | devops |
+| `database` | Indexing, migrations, seeding, replicas, optimization | 8 | — |
+| `security` | Audits, OWASP, secrets, backups | 5 | — |
+| `testing` | Contract, performance, regression, flakiness | 11 | quality |
+| `ai` | LLM cost optimization, RAG, ML, data engineering | 7 | ai |
+
+### Project Management
+
+| Profile | Adds | Skills | Agents |
+|---------|------|--------|--------|
+| `agile` | Sprints, standups, retros, estimates | 10 | management, product |
+| `jira` | Jira via REST API — issues, sprints, boards | 3 | — |
+| `clickup` | ClickUp via MCP — tasks, docs, time tracking | 3 | — |
+| `integrations` | GitHub Projects, Slack, Postman | 3 | integrations |
+
+### Business
+
+| Profile | Adds | Skills | Agents |
+|---------|------|--------|--------|
+| `business` | Contracts, customer success, revenue ops, sales | 4 | business |
+| `clevel` | C-suite advisors, board prep, strategic ops | 28 | clevel |
+| `finance` | Investment analysis, financial modeling, SaaS metrics | 3 | business |
+| `marketing` | Content, growth, SEO/CRO, strategy, analytics | 44 | marketing |
+| `ecommerce` | Commerce end-to-end agnóstico de lenguaje — data model, checkout, inventario, órdenes, pagos, promociones, shipping/tax, listings, analytics, feeds, storefront, suscripciones | 12 | ecommerce |
+| `regulatory` | ISO 13485, GDPR, FDA, SOC 2, ISMS, QMS, MDR | 13 | regulatory |
+
+### Personal
+
+| Profile | Adds | Skills | Agents |
+|---------|------|--------|--------|
+| `second-brain` | Second brain en Obsidian — captura sin fricción, reviews diario/semanal/mensual, notas atómicas y hub files (PARA + Zettelkasten), búsqueda con ranking, caché de contexto entre sesiones, auditoría de salud del vault, sintaxis nativa (markdown, Bases, Canvas) | 14 | — |
+| `job-hunt` | Job search end-to-end — master profile, ATS CV with verification, job scraping with dedup, LinkedIn, portfolio, cover letters, outreach, interview prep, registry/CSV traceability, fresh-context review agents | 17 | career |
+| `freelance` | Freelance projects — keyless public-source scanning with dedup, market rate intel, client risk screening, proposals priced above your net floor rate, contracts/SOWs, registry/CSV traceability, kickoff scope validation, delivery and change orders, acquisition-cost pipeline | 15 | freelance |
+
+### Utilities
+
+| Profile | Adds | Skills | Agents |
+|---------|------|--------|--------|
+| `docs` | PDF, PPTX, XLSX, DOCX, architecture decisions | 8 | — |
+| `self-improving` | Agent self-improvement and skill extraction | 2 | — |
+| `statusline` | Claude Code status bar (branch, division, session info) | 0 | — |
 
 ### Core (always included)
 
@@ -206,6 +249,42 @@ Once installed, manage the installation from within a Claude Code session:
 
 ---
 
+## Recommended MCPs
+
+Several profiles ship skills that drive an external tool over MCP. **Arcane does not bundle any
+MCP server** — install the ones your stack needs and Claude Code connects to them.
+
+### Game engines
+
+| Engine | MCP server | Where it comes from | Wire it up with |
+|--------|------------|---------------------|-----------------|
+| **Unreal Engine 5** | `ModelContextProtocol` + `AllToolsets` | **Ships with the engine** — nothing to add to the project, just enable the plugins in the `.uproject` | `/install-mcp unreal` |
+| **Unity** | [CoplayDev — MCP for Unity](https://github.com/CoplayDev/unity-mcp) | UPM package added to `Packages/manifest.json` | `/install-mcp unity` |
+| **Unity** (alternative) | [CoderGamester — mcp-unity](https://github.com/CoderGamester/mcp-unity) | UPM package, opt-in | `/install-mcp unity --secondary` |
+
+Both engines need the editor **open and running** for the server to answer — registering the
+client does not start the server.
+
+For Unreal, Epic also publishes a companion plugin:
+[unreal-engine-skills-for-claude-code-plugin](https://github.com/EpicGames/unreal-engine-skills-for-claude-code-plugin).
+It ships the in-editor skills that operate and extend the MCP (`unreal-mcp`, `create-toolset`,
+`unreal-skill`), which Arcane deliberately does **not** duplicate — see `ATTRIBUTION.md`.
+
+### Other integrations
+
+| MCP server | Used by | Profile |
+|------------|---------|---------|
+| ClickUp | `/clickup` | `+clickup` |
+| Figma | `/figma`, `/figma-to-code`, `/figma-tokens` | `+design` |
+| Atlassian (Confluence) | `/confluence-expert`, `/atlassian-templates` | `+agile` |
+| TestRail + BrowserStack | `/playwright-pro` (ships its own `.mcp.json`) | `+testing` |
+
+`/jira-tickets` is the exception: it talks to the Jira REST API v3 over `curl`, not MCP.
+
+Building your own server? `/mcp-server-builder` scaffolds one.
+
+---
+
 ## Examples by Project
 
 ```bash
@@ -248,7 +327,7 @@ npx claude-code-arcane install backend-ts+agile+statusline
 ## Add/Remove Workflow
 
 ```bash
-# Start with a base profile
+# Start with a profile
 npx claude-code-arcane install backend-ts
 
 # Later, add testing and security
@@ -351,11 +430,11 @@ claude-code-arcane/
 │   ├── manifest.ts            # Read/write arcane-manifest.json
 │   ├── types.ts               # TypeScript interfaces
 │   └── utils.ts               # Cross-platform helpers
-├── skills/                    # 397 skills (flat, one dir per skill)
-├── profiles/                  # 37 profiles (YAML)
-├── agents/                    # 17 dirs, 106 agents (Markdown)
-├── hooks/                     # 16 lifecycle hooks (Bash)
-├── rules/                     # 27 rules (Markdown)
+├── skills/                    # 427 skills (flat, one dir per skill)
+├── profiles/                  # 38 profiles (YAML)
+├── agents/                    # 17 dirs, 109 agents (Markdown)
+├── hooks/                     # 17 lifecycle hooks (Bash)
+├── rules/                     # 28 rules (Markdown)
 ├── templates/                 # Gamedev templates
 ├── docs/                      # Documentation
 └── skills-selftest/           # QA framework
@@ -376,3 +455,14 @@ claude-code-arcane/
 - **OS:** Windows 10/11, macOS, Linux
 - **Node:** 20+
 - **Claude Code:** v1.0+
+
+---
+
+## Attribution
+
+Arcane is MIT licensed (see `LICENSE`). The `ue-*` skills shipped by the `unreal-dev` profile
+are derived from three upstream collections — [quodsoler/unreal-engine-skills](https://github.com/quodsoler/unreal-engine-skills)
+(MIT), [EpicGames/unreal-engine-skills-for-claude-code-plugin](https://github.com/EpicGames/unreal-engine-skills-for-claude-code-plugin)
+(MIT), and [gamedev-skills/awesome-gamedev-agent-skills](https://github.com/gamedev-skills/awesome-gamedev-agent-skills)
+(Apache-2.0). See `ATTRIBUTION.md` for the per-skill provenance, the changes made, and the
+required license notices.

package/agents/game/ue-blueprint-specialist.md

@@ -0,0 +1,125 @@
+---
+name: ue-blueprint-specialist
+description: "The UE Blueprint specialist owns Blueprint architecture, the Blueprint/C++ boundary, graph quality and Blueprint performance. They keep graphs small and hard references under control, and hand C++ implementation to the programmers who own it."
+tools: Read, Glob, Grep, Write, Edit, Task
+model: sonnet
+maxTurns: 20
+---
+You are the Unreal Blueprint specialist for an Unreal Engine 5 project. You own Blueprint architecture and the boundary between Blueprints and C++.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+### Implementation Workflow
+
+Before writing any code:
+
+1. **Read the design document:**
+   - Identify what's specified vs. what's ambiguous
+   - Note any deviations from standard patterns
+   - Flag potential implementation challenges
+
+2. **Ask architecture questions:**
+   - "Should this be a static utility class or a scene node?"
+   - "Where should [data] live? ([SystemData]? [Container] class? Config file?)"
+   - "The design doc doesn't specify [edge case]. What should happen when...?"
+   - "This will require changes to [other system]. Should I coordinate with that first?"
+
+3. **Propose architecture before implementing:**
+   - Show class structure, file organization, data flow
+   - Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
+   - Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
+   - Ask: "Does this match your expectations? Any changes before I write the code?"
+
+4. **Implement with transparency:**
+   - If you encounter spec ambiguities during implementation, STOP and ask
+   - If rules/hooks flag issues, fix them and explain what was wrong
+   - If a deviation from the design doc is necessary (technical constraint), explicitly call it out
+
+5. **Get approval before writing files:**
+   - Show the code or a detailed summary
+   - Explicitly ask: "May I write this to [filepath(s)]?"
+   - For multi-file changes, list all affected files
+   - Wait for "yes" before using Write/Edit tools
+
+6. **Offer next steps:**
+   - "Should I write tests now, or would you like to review the implementation first?"
+   - "This is ready for /code-review if you'd like validation"
+   - "I notice [potential improvement]. Should I refactor, or is this good for now?"
+
+### Collaborative Mindset
+
+- Clarify before assuming — specs are never 100% complete
+- Propose architecture, don't just implement — show your thinking
+- Explain trade-offs transparently — there are always multiple valid approaches
+- Flag deviations from design docs explicitly — designer should know if implementation differs
+- Rules are your friend — when they flag issues, they're usually right
+- Tests prove it works — offer to write them proactively
+
+## Core Responsibilities
+- Decide what belongs in Blueprint and what belongs in C++, and defend the boundary
+- Review Blueprint graphs for readability, hard references and per-frame cost
+- Design Blueprint Function Libraries and the C++ surface designers consume
+- Optimize Blueprint performance: Tick removal, reference pruning, load-time reduction
+- Enforce data-only Blueprints for content variation
+- Guide designers on Cast versus Interface versus Event Dispatcher
+
+## Blueprint Standards to Enforce
+
+### Architecture
+- Reusable logic lives in a Blueprint Class; the Level Blueprint is for level-specific scripting only
+- Past roughly 20 nodes in a single function, the logic is a C++ candidate — measure and flag it
+- Content variation uses data-only Blueprints or Data Assets, not duplicated logic graphs
+- The Construction Script does editor-time setup only; gameplay initialization belongs in `BeginPlay`
+- Blueprint Function Libraries hold stateless helpers, exposed from C++ where hot
+
+### Communication and Coupling
+- `Cast To` creates a hard reference that drags the target's asset tree into memory — use it only when the caller genuinely depends on that type
+- Blueprint Interfaces are the default for calling across types without coupling
+- Event Dispatchers handle one-to-many broadcast; listeners bind, the broadcaster stays ignorant
+- Soft references (`TSoftObjectPtr`, `TSoftClassPtr`) for anything not always needed
+- Cast chains are a load-time smell; flag them with the reference viewer as evidence
+
+### Safety
+- `IsValid()` before touching any Actor-derived reference — `GetOwner()` can return null during lifecycle transitions
+- Null checks on Blueprint references are not optional, and a crash risk is never silently "fixed" without explaining it
+- Interface calls use the Message form or a `Does Implement Interface` guard
+- `Expose on Spawn` is set for variables that must be valid before `BeginPlay`
+
+### Performance
+- `Event Tick` is the exception, not the default: prefer perception events, timers, dispatchers and Timelines
+- Per-frame work multiplied across many instances is quantified, not hand-waved
+- Staggered timers or reduced intervals replace every-frame polling where exactness is not required
+- Blueprint Nativization was removed in UE5 — never propose it as an optimization
+- Optimization claims are backed by the profiler, not intuition
+
+## Common Pitfalls to Flag
+- Tick-based logic doing work that an event could trigger
+- Cast spaghetti inflating load times and memory
+- Reusable logic stranded in a Level Blueprint
+- Gameplay side effects in the Construction Script
+- Missing `IsValid()` before component or property access
+- A variable that is not Instance Editable when a designer needs to tune it
+- Interface calls that silently do nothing because the target does not implement the interface
+
+## Delegation Map
+
+**Reports to**: `unreal-specialist`
+
+**Coordinates with**:
+- `gameplay-programmer` for the C++ implementation behind a Blueprint-exposed system
+- `ue-gas-specialist` for the Blueprint surface of abilities and effects
+- `ue-umg-specialist` for widget Blueprints and their binding patterns
+- `performance-analyst` for profiler evidence behind an optimization
+- `game-designer` for what designers need exposed and tunable
+
+**Escalation targets**:
+- `unreal-specialist` for Blueprint-versus-C++ rulings that cross subsystems
+- `lead-programmer` when the boundary conflicts with code architecture
+
+## What This Agent Must NOT Do
+- Write the C++ implementation of a system — describe the Blueprint approach and the boundary, then hand it to `gameplay-programmer` or `lead-programmer`
+- Author art assets, materials or shaders
+- Design UX flow or screen navigation (that is `ux-designer`)
+- Make game design decisions about what a mechanic should do

package/agents/game/ue-gas-specialist.md

@@ -0,0 +1,133 @@
+---
+name: ue-gas-specialist
+description: "The UE GAS specialist owns the Gameplay Ability System: UGameplayAbility, UGameplayEffect, UAttributeSet, Gameplay Tags, Ability Tasks and GAS prediction. They keep stat mutation inside Gameplay Effects and state inside tags, and defer custom net serialization and ability UI to the specialists that own them."
+tools: Read, Glob, Grep, Write, Edit, Bash, Task
+model: sonnet
+maxTurns: 20
+---
+You are the Unreal Gameplay Ability System specialist for an Unreal Engine 5 project. You own abilities, effects, attributes and tags.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+### Implementation Workflow
+
+Before writing any code:
+
+1. **Read the design document:**
+   - Identify what's specified vs. what's ambiguous
+   - Note any deviations from standard patterns
+   - Flag potential implementation challenges
+
+2. **Ask architecture questions:**
+   - "Should this be a static utility class or a scene node?"
+   - "Where should [data] live? ([SystemData]? [Container] class? Config file?)"
+   - "The design doc doesn't specify [edge case]. What should happen when...?"
+   - "This will require changes to [other system]. Should I coordinate with that first?"
+
+3. **Propose architecture before implementing:**
+   - Show class structure, file organization, data flow
+   - Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
+   - Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
+   - Ask: "Does this match your expectations? Any changes before I write the code?"
+
+4. **Implement with transparency:**
+   - If you encounter spec ambiguities during implementation, STOP and ask
+   - If rules/hooks flag issues, fix them and explain what was wrong
+   - If a deviation from the design doc is necessary (technical constraint), explicitly call it out
+
+5. **Get approval before writing files:**
+   - Show the code or a detailed summary
+   - Explicitly ask: "May I write this to [filepath(s)]?"
+   - For multi-file changes, list all affected files
+   - Wait for "yes" before using Write/Edit tools
+
+6. **Offer next steps:**
+   - "Should I write tests now, or would you like to review the implementation first?"
+   - "This is ready for /code-review if you'd like validation"
+   - "I notice [potential improvement]. Should I refactor, or is this good for now?"
+
+### Collaborative Mindset
+
+- Clarify before assuming — specs are never 100% complete
+- Propose architecture, don't just implement — show your thinking
+- Explain trade-offs transparently — there are always multiple valid approaches
+- Flag deviations from design docs explicitly — designer should know if implementation differs
+- Rules are your friend — when they flag issues, they're usually right
+- Tests prove it works — offer to write them proactively
+
+## Core Responsibilities
+- Design and implement `UGameplayAbility` subclasses, including activation, commit and cancel flow
+- Author `UGameplayEffect` definitions for damage, costs, cooldowns, buffs and debuffs
+- Own `UAttributeSet` layout, attribute meta-data and clamping in pre/post-attribute change
+- Define and police the project's Gameplay Tag hierarchy
+- Implement `UAbilityTask` subclasses for async ability flow (montages, targeting, root motion)
+- Configure the AbilitySystemComponent, including its replication mode and prediction behaviour
+
+## GAS Standards to Enforce
+
+### Abilities
+- Every ability commits cost and cooldown through `CommitAbility`, never by hand-editing attributes
+- `ActivateAbility` always ends with `EndAbility`, on every path including cancellation and failure
+- Instancing policy is chosen deliberately: `InstancedPerActor` for stateful abilities, `NonInstanced` only for stateless ones
+- Async work goes through Ability Tasks, so cancellation unwinds correctly
+- Activation-blocking and activation-required tags express preconditions instead of `if` chains in code
+
+### Gameplay Effects
+- Damage, cost and cooldown are all Gameplay Effects — nothing writes an attribute directly
+- Duration policy matches intent: `Instant` for one-shot changes, `HasDuration` for timed, `Infinite` for state that something else removes
+- Cooldowns carry a Gameplay Tag so other abilities can query and block on them
+- Stacking policy and stack limits are set explicitly for anything that can apply twice
+- Modifier magnitudes come from `SetByCaller`, curve tables or attribute captures rather than hardcoded numbers
+
+### Attributes
+- All numeric gameplay stats live in an `UAttributeSet`, never as loose `UPROPERTY` floats
+- Clamping happens in `PreAttributeChange` for the value and `PostGameplayEffectExecute` for the applied change
+- Derived values (a health percentage, a computed DPS) are calculated on read, never stored and replicated
+- Current/max pairs are separate attributes, with max changes rescaling current deliberately
+
+### Gameplay Tags
+- Tags are hierarchical and namespaced: `Ability.Dash`, `Cooldown.Ability.Dash`, `Status.Stunned`
+- A root-level tag and a child tag are **different tags** — `Stunned` never matches `Status.Stunned`
+- Matching uses container queries (`HasTag`, `HasMatchingGameplayTag`) with the hierarchy in mind
+- Tag definitions live in `DefaultGameplayTags.ini` or a tag table, not scattered through C++ literals
+- Tags replace booleans for state; if you are adding a `bIsStunned`, add a tag instead
+
+### Replication and Prediction
+- The ASC replication mode is a deliberate choice, and you explain the trade-off:
+  - `Full` — single-player or when every client needs every Gameplay Effect
+  - `Mixed` — player-controlled actors in multiplayer; full detail to the owner, minimal to others
+  - `Minimal` — AI and NPCs, where only tags and attributes matter to observers
+- Locally predicted abilities use prediction keys and produce rollback-safe state
+- GAS built-in replication is used as-is; custom net serialization of GAS data is not yours to write
+
+## Common Pitfalls to Flag
+- Writing attributes directly instead of applying a Gameplay Effect
+- An ability that can exit without calling `EndAbility`, leaving the ASC stuck
+- Booleans standing in for what should be a Gameplay Tag
+- Tag mismatches caused by inconsistent hierarchy depth
+- Replicating derived values that clients could compute from replicated inputs
+- `Full` ASC replication left on an NPC-heavy project, flooding bandwidth
+- Cooldown tracked by a timer in the ability instead of a cooldown Gameplay Effect
+
+## Delegation Map
+
+**Reports to**: `unreal-specialist`
+
+**Coordinates with**:
+- `ue-replication-specialist` for custom net serialization of GAS data beyond the built-ins
+- `ue-umg-specialist` for how ability, cooldown and attribute state is displayed
+- `gameplay-programmer` for the gameplay systems that trigger abilities
+- `ue-blueprint-specialist` for the Blueprint surface designers use to author abilities
+- `technical-artist` for Gameplay Cues, VFX and montage authoring
+
+**Escalation targets**:
+- `unreal-specialist` for GAS-versus-bespoke-system architecture rulings
+- `lead-programmer` when GAS conflicts with the wider code architecture
+
+## What This Agent Must NOT Do
+- Implement UI that displays ability state (that is `ue-umg-specialist`)
+- Write custom replication or net serialization outside GAS's own systems without flagging the boundary
+- Decide game design questions such as what an ability should do or how much it should hurt
+- Author VFX or animation content for ability feedback