@ai-kits/wp-ag-kit 1.0.0

package/bin/antigravity-agent.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_SKILLS_ROOT = path.resolve(__dirname, '..');
+const AGENT_SKILLS_SKILLS = path.join(AGENT_SKILLS_ROOT, 'skills');
+
+function printHelp() {
+    console.log(`WordPress Antigravity Kit CLI\n\nUsage:\n  wpag <command> [args]\n\nCommands:\n  init                 Initialize .agent folder in current project\n  list-skills          List available skills from the kit\n  list-agents          List available agents from the kit\n  list-installed       List items currently installed in .agent/\n  use-skill <name>     Copy a specific skill into .agent/skills\n  help                 Show this help message\n`);
+}
+
+function initAgentFolder() {
+    const target = path.resolve(process.cwd(), '.agent');
+    const AGENT_SKILLS_SHARED = path.join(AGENT_SKILLS_ROOT, 'shared');
+    const AGENT_SKILLS_AGENTS = path.join(AGENT_SKILLS_ROOT, 'agents');
+    const AGENT_SKILLS_WORKFLOWS = path.join(AGENT_SKILLS_ROOT, 'workflows');
+    const AGENT_SKILLS_RULES = path.join(AGENT_SKILLS_ROOT, 'rules');
+
+    if (!fs.existsSync(target)) {
+        fs.mkdirSync(target);
+        console.log('Created .agent folder');
+    } else {
+        console.log('.agent folder already exists');
+    }
+
+    const foldersToCopy = [
+        { name: 'skills', src: AGENT_SKILLS_SKILLS },
+        { name: 'shared', src: AGENT_SKILLS_SHARED },
+        { name: 'agents', src: AGENT_SKILLS_AGENTS },
+        { name: 'workflows', src: AGENT_SKILLS_WORKFLOWS },
+        { name: 'rules', src: AGENT_SKILLS_RULES }
+    ];
+
+    foldersToCopy.forEach(folder => {
+        const dest = path.join(target, folder.name);
+        if (fs.existsSync(folder.src)) {
+            if (!fs.existsSync(dest)) {
+                copyDirRecursive(folder.src, dest);
+                console.log(`Copied "${folder.name}" to .agent/${folder.name}`);
+            } else {
+                console.log(`.agent/${folder.name} already exists.`);
+            }
+        }
+    });
+}
+
+function copyDirRecursive(src, dest) {
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach(item => {
+        const srcPath = path.join(src, item);
+        const destPath = path.join(dest, item);
+        if (fs.statSync(srcPath).isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    });
+}
+
+function listSkills() {
+    if (!fs.existsSync(AGENT_SKILLS_SKILLS)) {
+        console.error('Skills directory not found in kit.');
+        process.exit(1);
+    }
+    const skills = fs.readdirSync(AGENT_SKILLS_SKILLS).filter(f => fs.statSync(path.join(AGENT_SKILLS_SKILLS, f)).isDirectory());
+    console.log('Available skills in kit:');
+    skills.forEach(skill => console.log('  -', skill));
+}
+
+function listAgents() {
+    const AGENT_SKILLS_AGENTS = path.join(AGENT_SKILLS_ROOT, 'agents');
+    if (!fs.existsSync(AGENT_SKILLS_AGENTS)) {
+        console.log('No agents directory found in kit.');
+        return;
+    }
+    const agents = fs.readdirSync(AGENT_SKILLS_AGENTS).filter(f => f.endsWith('.md'));
+    console.log('Available agents in kit:');
+    agents.forEach(agent => console.log('  -', agent));
+}
+
+function listInstalled() {
+    const target = path.resolve(process.cwd(), '.agent');
+    if (!fs.existsSync(target)) {
+        console.log('No .agent folder found. Run "ag-agent init".');
+        return;
+    }
+
+    const subs = ['skills', 'agents', 'workflows', 'rules'];
+    subs.forEach(sub => {
+        const subPath = path.join(target, sub);
+        if (fs.existsSync(subPath)) {
+            const items = fs.readdirSync(subPath);
+            console.log(`Installed in .agent/${sub}:`);
+            if (items.length === 0) {
+                console.log('  (none)');
+            } else {
+                items.forEach(item => console.log('  -', item));
+            }
+        }
+    });
+}
+
+
+function useSkill(skillName) {
+    const target = path.resolve(process.cwd(), '.agent/skills');
+    if (!fs.existsSync(target)) {
+        console.error('No .agent/skills folder found. Run ag-agent init first.');
+        process.exit(1);
+    }
+    const src = path.join(AGENT_SKILLS_SKILLS, skillName);
+    const dest = path.join(target, skillName);
+    if (!fs.existsSync(src)) {
+        console.error('Skill not found:', skillName);
+        process.exit(1);
+    }
+    if (fs.existsSync(dest)) {
+        console.log('Skill already exists in .agent/skills:', skillName);
+        return;
+    }
+    copyDirRecursive(src, dest);
+    console.log('Copied skill', skillName, 'to .agent/skills');
+}
+
+const cmd = process.argv[2];
+const arg = process.argv[3];
+
+switch (cmd) {
+    case 'init':
+        initAgentFolder();
+        break;
+    case 'list-skills':
+        listSkills();
+        break;
+    case 'list-agents':
+        listAgents();
+        break;
+    case 'list-installed':
+        listInstalled();
+        break;
+    case 'use-skill':
+        if (!arg) {
+            console.error('Please specify a skill name.');
+            process.exit(1);
+        }
+        useSkill(arg);
+        break;
+    case 'help':
+    case undefined:
+        printHelp();
+        break;
+    default:
+        console.error('Unknown command:', cmd);
+        printHelp();
+        process.exit(1);
+}

package/docs/authoring-guide.md

@@ -0,0 +1,56 @@
+# Authoring guide (AI-assisted)
+
+This repo is built for **AI-assisted authoring** with **deterministic guardrails**.
+
+## Golden rules
+
+- Keep `SKILL.md` short and procedural; push depth into `references/` and scripts.
+- Prefer deterministic scripts for anything the agent would otherwise “guess” (repo detection, version checks, lint/test command discovery).
+- Don’t add a new skill without at least one scenario in `eval/scenarios/`.
+- Keep file references 1 hop from `SKILL.md` (avoid deep chains).
+- Include a `compatibility:` frontmatter line matching `docs/compatibility-policy.md`.
+
+## Workflow: draft → harden → ship
+
+1. **Route first**
+   - Start from `skills/wordpress-router/SKILL.md` to classify the repo and pick the domain.
+2. **Collect inputs**
+   - What repo type(s) does triage detect?
+   - What WP/PHP/Node versions are targeted (if known)?
+   - What tooling exists (Composer, @wordpress/scripts, PHPUnit, Playwright, wp-env)?
+3. **Draft the skill (AI-assisted)**
+   - Write `SKILL.md` as a checklist/procedure with explicit “Verification” and “Failure modes”.
+   - Keep examples short; link to topic references when needed.
+4. **Add deterministic helpers**
+   - If the skill depends on detection (versions, project layout, build system), add a script under `scripts/`.
+5. **Add evaluation scenario(s)**
+   - Add at least 1 prompt-style scenario under `eval/scenarios/` describing expected behavior.
+6. **Validate**
+   - Run `node eval/harness/run.mjs`.
+   - Optionally validate frontmatter using `skills-ref validate` (see `docs/upstream-sync.md` for CI guidance).
+
+## Scaffolding a new skill
+
+Use the scaffold script to create a minimal, spec-compliant starting point:
+
+- `node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"`
+
+## “Skill generation” prompt template (recommended)
+
+When using an LLM to draft a skill, provide:
+
+- The repo triage JSON output
+- The user’s task statement(s)
+- Any version constraints and non-goals
+- The required sections: When to use, Inputs required, Procedure, Verification, Failure modes, Escalation
+
+Then ask the model to output:
+
+1. `skills/<skill-name>/SKILL.md`
+2. Any `references/*.md` files it mentions
+3. Any `scripts/*` stubs needed for deterministic checks
+4. One scenario markdown file under `eval/scenarios/`
+
+## Suggested initial domain skills (v1)
+
+See `docs/skill-set-v1.md`.

package/docs/compatibility-policy.md

@@ -0,0 +1,18 @@
+# Compatibility policy
+
+This repo is an authoring workspace for WordPress-focused Agent Skills.
+
+## Compatibility contract (v1)
+
+Skills in this repo target:
+
+- WordPress core **6.9+**
+- PHP **7.2.24+** (minimum supported by WordPress 6.9)
+
+## Authoring rules
+
+Skills should:
+
+- Prefer stable WordPress APIs and best practices.
+- Prefer detection + guardrails (triage) over hard-coded assumptions.
+- If a task requires behavior that differs across core versions, ask for a target version (but default guidance should assume WP 6.9+).

package/docs/packaging.md

@@ -0,0 +1,26 @@
+# Packaging and installation
+
+This repo is the **source of truth** under `skills/`.
+
+To distribute skills to other repos/tools (without symlinks), use the skillpack scripts.
+
+## Build dist
+
+Build a packaged copy under `dist/`:
+
+- `node shared/scripts/skillpack-build.mjs --clean`
+
+Outputs:
+
+- `dist/codex/.codex/skills/*` (OpenAI Codex repo layout)
+- `dist/vscode/.github/skills/*` (VS Code / Copilot repo layout)
+
+## Install into another repo
+
+1. Build dist (above).
+2. Install into a destination repo:
+
+- `node shared/scripts/skillpack-install.mjs --dest=../some-repo --targets=codex,vscode`
+
+By default, install mode is `replace` (it replaces only the skill directories it installs).
+

package/docs/principles.md

@@ -0,0 +1,7 @@
+# Principles
+
+- Prefer small, composable skills over a single "mega-skill".
+- Keep `SKILL.md` bodies short; move depth into `references/`.
+- Bundle deterministic checks as scripts when reliability matters.
+- Treat upstream docs as canonical; store agent-first checklists and decision trees.
+- Every new skill must include at least one eval scenario under `eval/scenarios/`.

package/docs/skill-set-v1.md

@@ -0,0 +1,21 @@
+# WordPress skill set (v1)
+
+This repo currently includes:
+
+- `wordpress-router`
+- `wp-project-triage`
+- `wp-block-development`
+- `wp-block-themes`
+- `wp-plugin-development`
+- `wp-rest-api`
+- `wp-interactivity-api`
+- `wp-abilities-api`
+- `wp-wpcli-and-ops`
+- `wp-performance`
+- `wp-phpstan`
+
+Planned next skills (not yet implemented):
+
+- `wp-build-tooling`
+- `wp-testing`
+- `wp-security`

package/docs/upstream-sync.md

@@ -0,0 +1,52 @@
+# Upstream sync (automation plan)
+
+Goal: when upstream changes (WordPress core releases, Gutenberg releases, docs updates), the repo should **regenerate indexes** and (eventually) **open PRs** that update affected skills/references.
+
+## What to automate first (low risk)
+
+1. **Indexes and matrices**
+   - WordPress core version list (latest stable + recent).
+   - Gutenberg releases list (latest stable + recent).
+   - WordPress ↔ Gutenberg mapping table (derived from canonical docs where available).
+2. **Routing metadata refresh**
+   - Update `shared/references/*.json` files only.
+
+This keeps automation deterministic and reviewable before it starts rewriting skill prose.
+
+## Later automation (higher risk)
+
+- “Reference chunk regeneration” from upstream docs into `skills/*/references/*.md`.
+- Task-shaped deltas (e.g. a new Gutenberg package, new block APIs, changes in theme.json schema).
+- Semi-automated PRs that include:
+  - regenerated references
+  - updated checklists
+  - updated eval scenarios
+
+## Scripts
+
+- `shared/scripts/update-upstream-indices.mjs`
+  - Fetches upstream sources and rewrites JSON indexes in `shared/references/`.
+
+## CI / PR bot design (recommended)
+
+- Schedule a workflow (daily/weekly).
+- Run `shared/scripts/update-upstream-indices.mjs`.
+- If `git diff` is non-empty, open a PR with:
+  - a summary of changes
+  - links to upstream release notes
+  - a checklist for human review (“does this impact blocks/themes/plugin workflows?”)
+
+## Validation
+
+- Always run `node eval/harness/run.mjs`.
+- Optional: use Agent Skills reference validator:
+  - `skills-ref validate skills/<skill-name>`
+
+## Canonical sources
+
+The automation should prefer canonical sources and avoid scraping where possible.
+
+- WordPress core releases and API endpoints (official WordPress APIs)
+- Gutenberg releases (GitHub releases)
+- WordPress developer docs (used for the WP↔Gutenberg mapping when no API exists)
+

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@ai-kits/wp-ag-kit",
+	"version": "1.0.0",
+	"description": "WordPress Antigravity Kit - Complete WordPress development environment for Antigravity IDE with skills, agents, workflows, and rules.",
+	"main": "bin/antigravity-agent.js",
+	"bin": {
+		"wpag": "bin/antigravity-agent.js"
+	},
+	"scripts": {
+		"test": "node eval/harness/run.mjs",
+		"build": "node shared/scripts/skillpack-build.mjs --clean",
+		"prepublishOnly": "npm test"
+	},
+	"author": "Anikesh Kumar",
+	"license": "MIT",
+	"keywords": [
+		"wordpress",
+		"antigravity",
+		"gutenberg",
+		"blocks",
+		"agent",
+		"ai",
+		"cli",
+		"skills",
+		"block-themes",
+		"interactivity-api",
+		"wp-cli",
+		"phpstan",
+		"ai-kits"
+	],
+	"files": [
+		"bin/",
+		"skills/",
+		"agents/",
+		"workflows/",
+		"rules/",
+		"shared/",
+		"docs/",
+		"README.md",
+		"ANTIGRAVITY-README.md",
+		"STRUCTURE.md",
+		"CONTRIBUTING.md"
+	],
+	"engines": {
+		"node": ">=16"
+	}
+}

package/rules/GEMINI.md

@@ -0,0 +1,273 @@
+---
+trigger: always_on
+---
+
+# GEMINI.md - Antigravity Kit
+
+> This file defines how the AI behaves in this workspace.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+
+Agent activated → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent .md) > P2 (SKILL.md). All rules are binding.
+
+### 2. Enforcement Protocol
+
+1. **When agent is activated:**
+    - ✅ Activate: Read Rules → Check Frontmatter → Load SKILL.md → Apply All.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+
+---
+
+## 📥 REQUEST CLASSIFIER (STEP 1)
+
+**Before ANY action, classify the request:**
+
+| Request Type     | Trigger Keywords                           | Active Tiers                   | Result                      |
+| ---------------- | ------------------------------------------ | ------------------------------ | --------------------------- |
+| **QUESTION**     | "what is", "how does", "explain"           | TIER 0 only                    | Text Response               |
+| **SURVEY/INTEL** | "analyze", "list files", "overview"        | TIER 0 + Explorer              | Session Intel (No File)     |
+| **SIMPLE CODE**  | "fix", "add", "change" (single file)       | TIER 0 + TIER 1 (lite)         | Inline Edit                 |
+| **COMPLEX CODE** | "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **DESIGN/UI**    | "design", "UI", "page", "dashboard"        | TIER 0 + TIER 1 + Agent        | **{task-slug}.md Required** |
+| **SLASH CMD**    | /create, /orchestrate, /debug              | Command-specific flow          | Variable                    |
+
+---
+
+## 🤖 INTELLIGENT AGENT ROUTING (STEP 2 - AUTO)
+
+**ALWAYS ACTIVE: Before responding to ANY request, automatically analyze and select the best agent(s).**
+
+> 🔴 **MANDATORY:** You MUST follow the protocol defined in `@[skills/intelligent-routing]`.
+
+### Auto-Selection Protocol
+
+1. **Analyze (Silent)**: Detect domains (Frontend, Backend, Security, etc.) from user request.
+2. **Select Agent(s)**: Choose the most appropriate specialist(s).
+3. **Inform User**: Concisely state which expertise is being applied.
+4. **Apply**: Generate response using the selected agent's persona and rules.
+
+### Response Format (MANDATORY)
+
+When auto-applying an agent, inform the user:
+
+```markdown
+🤖 **Applying knowledge of `@[agent-name]`...**
+
+[Continue with specialized response]
+```
+
+**Rules:**
+
+1. **Silent Analysis**: No verbose meta-commentary ("I am analyzing...").
+2. **Respect Overrides**: If user mentions `@agent`, use it.
+3. **Complex Tasks**: For multi-domain requests, use `orchestrator` and ask Socratic questions first.
+
+### ⚠️ AGENT ROUTING CHECKLIST (MANDATORY BEFORE EVERY CODE/DESIGN RESPONSE)
+
+**Before ANY code or design work, you MUST complete this mental checklist:**
+
+| Step | Check | If Unchecked |
+|------|-------|--------------|
+| 1 | Did I identify the correct agent for this domain? | → STOP. Analyze request domain first. |
+| 2 | Did I READ the agent's `.md` file (or recall its rules)? | → STOP. Open `.agent/agents/{agent}.md` |
+| 3 | Did I announce `🤖 Applying knowledge of @[agent]...`? | → STOP. Add announcement before response. |
+| 4 | Did I load required skills from agent's frontmatter? | → STOP. Check `skills:` field and read them. |
+
+**Failure Conditions:**
+
+- ❌ Writing code without identifying an agent = **PROTOCOL VIOLATION**
+- ❌ Skipping the announcement = **USER CANNOT VERIFY AGENT WAS USED**
+- ❌ Ignoring agent-specific rules (e.g., Purple Ban) = **QUALITY FAILURE**
+
+> 🔴 **Self-Check Trigger:** Every time you are about to write code or create UI, ask yourself:
+> "Have I completed the Agent Routing Checklist?" If NO → Complete it first.
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in English:
+
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+### 🧹 Clean Code (Global Mandatory)
+
+**ALL code MUST follow `@[skills/clean-code]` rules. No exceptions.**
+
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to 2025 standards (Core Web Vitals).
+- **Infra/Safety**: 5-Phase Deployment. Verify secrets security.
+
+### 📁 File Dependency Awareness
+
+**Before modifying ANY file:**
+
+1. Check `CODEBASE.md` → File Dependencies
+2. Identify dependent files
+3. Update ALL affected files together
+
+### 🗺️ System Map Read
+
+> 🔴 **MANDATORY:** Read `ARCHITECTURE.md` at session start to understand Agents, Skills, and Scripts.
+
+**Path Awareness:**
+
+- Agents: `.agent/` (Project)
+- Skills: `.agent/skills/` (Project)
+- Runtime Scripts: `.agent/skills/<skill>/scripts/`
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## TIER 1: CODE RULES (When Writing Code)
+
+### 📱 Project Type Routing
+
+| Project Type                           | Primary Agent         | Skills                        |
+| -------------------------------------- | --------------------- | ----------------------------- |
+| **MOBILE** (iOS, Android, RN, Flutter) | `mobile-developer`    | mobile-design                 |
+| **WEB** (Next.js, React web)           | `frontend-specialist` | frontend-design               |
+| **BACKEND** (API, server, DB)          | `backend-specialist`  | api-patterns, database-design |
+
+> 🔴 **Mobile + frontend-specialist = WRONG.** Mobile = mobile-developer ONLY.
+
+### 🛑 Socratic Gate
+
+**For complex requests, STOP and ASK first:**
+
+### 🛑 GLOBAL SOCRATIC GATE (TIER 0)
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type            | Strategy       | Required Action                                                   |
+| ----------------------- | -------------- | ----------------------------------------------------------------- |
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions                                 |
+| **Code Edit / Bug Fix** | Context Check  | Confirm understanding + ask impact questions                      |
+| **Vague / Simple**      | Clarification  | Ask Purpose, Users, and Scope                                     |
+| **Full Orchestration**  | Gatekeeper     | **STOP** subagents until user confirms plan details               |
+| **Direct "Proceed"**    | Validation     | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:**
+
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+4. **Reference:** Full protocol in `@[skills/brainstorming]`.
+
+### 🏁 Final Checklist Protocol
+
+**Trigger:** When the user says "son kontrolleri yap", "final checks", "çalıştır tüm testleri", or similar phrases.
+
+| Task Stage       | Command                                            | Purpose                        |
+| ---------------- | -------------------------------------------------- | ------------------------------ |
+| **Manual Audit** | `python .agent/scripts/checklist.py .`             | Priority-based project audit   |
+| **Pre-Deploy**   | `python .agent/scripts/checklist.py . --url <URL>` | Full Suite + Performance + E2E |
+
+**Priority Execution Order:**
+
+1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **UX** → 6. **Seo** → 7. **Lighthouse/E2E**
+
+**Rules:**
+
+- **Completion:** A task is NOT finished until `checklist.py` returns success.
+- **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
+
+**Available Scripts (12 total):**
+
+| Script                     | Skill                 | When to Use         |
+| -------------------------- | --------------------- | ------------------- |
+| `security_scan.py`         | vulnerability-scanner | Always on deploy    |
+| `dependency_analyzer.py`   | vulnerability-scanner | Weekly / Deploy     |
+| `lint_runner.py`           | lint-and-validate     | Every code change   |
+| `test_runner.py`           | testing-patterns      | After logic change  |
+| `schema_validator.py`      | database-design       | After DB change     |
+| `ux_audit.py`              | frontend-design       | After UI change     |
+| `accessibility_checker.py` | frontend-design       | After UI change     |
+| `seo_checker.py`           | seo-fundamentals      | After page change   |
+| `bundle_analyzer.py`       | performance-profiling | Before deploy       |
+| `mobile_audit.py`          | mobile-design         | After mobile change |
+| `lighthouse_audit.py`      | performance-profiling | Before deploy       |
+| `playwright_runner.py`     | webapp-testing        | Before deploy       |
+
+> 🔴 **Agents & Skills can invoke ANY script** via `python .agent/skills/<skill>/scripts/<script>.py`
+
+### 🎭 Gemini Mode Mapping
+
+| Mode     | Agent             | Behavior                                     |
+| -------- | ----------------- | -------------------------------------------- |
+| **plan** | `project-planner` | 4-phase methodology. NO CODE before Phase 4. |
+| **ask**  | -                 | Focus on understanding. Ask questions.       |
+| **edit** | `orchestrator`    | Execute. Check `{task-slug}.md` first.       |
+
+**Plan Mode (4-Phase):**
+
+1. ANALYSIS → Research, questions
+2. PLANNING → `{task-slug}.md`, task breakdown
+3. SOLUTIONING → Architecture, design (NO CODE!)
+4. IMPLEMENTATION → Code + tests
+
+> 🔴 **Edit mode:** If multi-file or structural change → Offer to create `{task-slug}.md`. For single-file fixes → Proceed directly.
+
+---
+
+## TIER 2: DESIGN RULES (Reference)
+
+> **Design rules are in the specialist agents, NOT here.**
+
+| Task         | Read                            |
+| ------------ | ------------------------------- |
+| Web UI/UX    | `.agent/frontend-specialist.md` |
+| Mobile UI/UX | `.agent/mobile-developer.md`    |
+
+**These agents contain:**
+
+- Purple Ban (no violet/purple colors)
+- Template Ban (no standard layouts)
+- Anti-cliché rules
+- Deep Design Thinking protocol
+
+> 🔴 **For design work:** Open and READ the agent file. Rules are there.
+
+---
+
+## 📁 QUICK REFERENCE
+
+### Agents & Skills
+
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor` (Cyber/Audit), `backend-specialist` (API/DB), `frontend-specialist` (UI/UX), `mobile-developer`, `debugger`, `game-developer`
+- **Key Skills**: `clean-code`, `brainstorming`, `app-builder`, `frontend-design`, `mobile-design`, `plan-writing`, `behavioral-modes`
+
+### Key Scripts
+
+- **Verify**: `.agent/scripts/verify_all.py`, `.agent/scripts/checklist.py`
+- **Scanners**: `security_scan.py`, `dependency_analyzer.py`
+- **Audits**: `ux_audit.py`, `mobile_audit.py`, `lighthouse_audit.py`, `seo_checker.py`
+- **Test**: `playwright_runner.py`, `test_runner.py`
+
+---

package/shared/references/.gitkeep

@@ -0,0 +1 @@
+