@musashishao/agent-kit 1.6.2 → 1.8.0

package/.agent/rules/CODEX.md

@@ -99,18 +99,19 @@ For each domain, apply corresponding skill:
 ```
 
 ### Rule 4: Socratic Gate
-For complex/unclear requests, ASK before implementing:
-```
-Before I implement, let me clarify:
-1. [Specific question about scope]
-2. [Specific question about requirements]
-3. [Specific question about constraints]
-```
+For complex/unclear requests, ASK before implementing. Follow the **One Question at a Time** protocol.
 
 ---
 
 ## 📂 SKILL QUICK REFERENCE
 
+### Core & Workflow
+```
+/read .agent/skills/verification-gate/SKILL.md
+/read .agent/skills/git-worktrees/SKILL.md
+/read .agent/skills/parallel-agents/SKILL.md
+```
+
 ### Frontend Development
 ```
 /read .agent/skills/react-patterns/SKILL.md

package/.agent/rules/CODE_RULES.md

@@ -58,6 +58,21 @@ trigger: always_on
 
 ---
 
+## 🔴 VERIFICATION GATE (IRON LAW)
+
+**MANDATORY: Before ANY claim of success or completion.**
+
+| Rule | Action |
+|------|--------|
+| **Evidence First** | Run the specific command that proves the claim. |
+| **No "Should"** | Stop using "should work" or "probably fixed". |
+| **Fresh Data** | Verification must be run on the LATEST version of code. |
+| **Two-Stage Review** | For orchestration, use Spec Review → Quality Review. |
+
+**Protocol:** If you haven't run the verification command in the current turn, you CANNOT claim success. Apply `@[skills/verification-gate]`.
+
+---
+
 ## 🎭 Gemini Mode Mapping
 
 | Mode | Agent | Behavior |

package/.agent/rules/REFERENCE.md

@@ -28,12 +28,17 @@ trigger: always_on
 | Skill | Purpose |
 |-------|---------|
 | `clean-code` | Coding standards (GLOBAL) |
-| `brainstorming` | Socratic questioning |
+| `brainstorming` | Socratic questioning + one-question protocol |
+| `verification-gate` | Evidence-based completion claims (NEW) |
+| `git-worktrees` | Isolated branch development (NEW) |
 | `spec-writing` | SPEC-{slug}.md format (SDD) |
 | `plan-writing` | PLAN-{slug}.md format |
 | `app-builder` | Full-stack orchestration |
-| `frontend-design` | Web UI patterns |
+| `react-patterns` | React/Next.js patterns + 57 performance rules |
+| `web-interface-guidelines` | UI audit (forms, touch, a11y, anti-patterns) |
+| `frontend-design` | Web UI patterns + anti-AI-slop rules |
 | `mobile-design` | Mobile UI patterns |
+| `parallel-agents` | Multi-agent orchestration + two-stage review |
 | `behavioral-modes` | Mode switching |
 | `ai-security-guardrails` | OWASP Top 10 for LLMs, prompt injection defense |
 | `privacy-preserving-dev` | PII detection and redaction patterns |

package/.agent/skills/brainstorming/SKILL.md

@@ -30,6 +30,58 @@ allowed-tools: Read, Glob, Grep
    - 📦 Scope: Must-have vs nice-to-have?
 3. **WAIT** - Get response before proceeding
 
+### ☝️ ONE QUESTION AT A TIME (Superpowers Protocol)
+
+> **Core Principle:** Don't overwhelm. One question per message.
+
+| Rule | Rationale |
+|------|-----------|
+| **One question per message** | Easier to answer, clearer responses |
+| **Multiple choice preferred** | Faster decisions than open-ended |
+| **Explore before drilling** | Breadth first, depth on selected areas |
+| **Break complex topics** | If topic needs exploration, use multiple questions |
+
+**Example Flow:**
+```
+❌ WRONG: "What framework, styling, and auth method do you prefer?"
+
+✅ CORRECT:
+Message 1: "Which framework? (A) Next.js (B) React+Vite (C) Vue"
+[Wait for answer]
+Message 2: "For styling, what approach? (A) Tailwind (B) CSS Modules (C) styled-components"
+[Wait for answer]
+```
+
+### 📄 Incremental Design Validation
+
+> **Present design in 200-300 word sections, validate each before proceeding**
+
+**Process:**
+1. Once you understand requirements, START presenting design
+2. Break into digestible sections (200-300 words each)
+3. After EACH section, ask: "Does this look right so far?"
+4. Only proceed to next section after confirmation
+5. Be ready to backtrack if something doesn't make sense
+
+**Section Order:**
+```
+1. Architecture Overview (200-300 words) → Validate ✅
+2. Data Model (200-300 words) → Validate ✅
+3. Key Components (200-300 words) → Validate ✅
+4. User Flows (200-300 words) → Validate ✅
+5. Error Handling (200-300 words) → Validate ✅
+```
+
+### 🎯 YAGNI Ruthlessly
+
+> Remove unnecessary features from ALL designs
+
+| Question | If Answer is "Maybe" |
+|----------|---------------------|
+| "Do we need this feature now?" | Remove it |
+| "Will users definitely use this?" | Defer it |
+| "Is this essential for v1?" | Cut scope |
+
 ---
 
 ## 🧠 Dynamic Question Generation

package/.agent/skills/frontend-design/SKILL.md

@@ -340,6 +340,36 @@ For animation patterns: [animation-guide.md](animation-guide.md), for advanced:
 - **Same layout structure / Vercel clone**
 - **Not asking user preferences**
 
+### 🚫 FORBIDDEN PATTERNS (Anti-AI-Slop)
+
+> Adapted from Anthropic's frontend-design skill
+
+| Element | 🚫 FORBIDDEN | ✅ USE INSTEAD |
+|---------|--------------|----------------|
+| **Fonts** | Inter, Roboto, Arial, system fonts | Distinctive display fonts (IBM Plex, Outfit, Space Mono, Bricolage Grotesque) |
+| **Colors** | Purple gradients on white, fintech blue/cyan | Bold, context-specific palettes (Red + Black, Neon Green, Earth tones) |
+| **Layouts** | Centered cards, hero split (left/right), predictable grids | Asymmetry, overlap, diagonal flow, massive typography |
+| **Backgrounds** | Solid colors, generic mesh/aurora gradients | Gradient meshes (unique), noise textures, geometric patterns |
+| **Effects** | Default shadows, cookie-cutter glassmorphism | Layered transparencies, dramatic shadows, grain overlays |
+| **Copy** | "Orchestrate", "Empower", "Seamless" | Human language, context-specific |
+
+### 🎨 Bold Aesthetic Direction (REQUIRED)
+
+**Before coding, commit to ONE extreme:**
+
+| Direction | Characteristics |
+|-----------|-----------------|
+| **Brutally Minimal** | Zero decoration, massive type, stark contrast |
+| **Maximalist Chaos** | Dense, layered, overwhelming intentionally |
+| **Retro-Futuristic** | 80s/90s tech meets modern |
+| **Organic/Natural** | Flowing shapes, earth tones, imperfection |
+| **Luxury/Refined** | Restrained elegance, whitespace, gold/black |
+| **Playful/Toy-like** | Bright, rounded, childlike joy |
+| **Editorial/Magazine** | Grid-based, type-heavy, sophisticated |
+| **Brutalist/Raw** | Exposed structure, ugly-beautiful |
+
+> **Remember:** Generic AI aesthetics = FAILURE. Every design must be memorable.
+
 ### ❌ Dark Patterns (Unethical)
 
 - Hidden costs

package/.agent/skills/git-worktrees/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: git-worktrees
+description: Isolated branch development using git worktrees. Use when starting new features, experiments, or parallel development. Creates clean workspace on new branch without affecting main checkout.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+# Git Worktrees for Isolated Development
+
+> **Core Principle:** Isolated workspaces prevent context pollution and enable clean experimentation.
+
+---
+
+## 🎯 When to Use
+
+| Situation | Use Worktrees? |
+|-----------|----------------|
+| New feature development | ✅ Yes |
+| Experimental changes | ✅ Yes |
+| Bug fix that might break things | ✅ Yes |
+| Quick hotfix on main | ❌ No, direct |
+| Review someone's PR | ✅ Yes |
+| Parallel feature work | ✅ Yes |
+
+---
+
+## 📁 Directory Selection Process
+
+### 1. Check for Existing Worktree Directory
+
+```bash
+# Check if project has worktree directory
+if [ -d ".worktrees" ]; then
+    WORKTREE_DIR=".worktrees"
+elif [ -d "worktrees" ]; then
+    WORKTREE_DIR="worktrees"
+else
+    # Create new
+    WORKTREE_DIR=".worktrees"
+    mkdir -p "$WORKTREE_DIR"
+fi
+```
+
+### 2. Verify .gitignore Contains Worktree Directory
+
+```bash
+# CRITICAL: Ensure worktree directory is ignored
+if ! grep -q ".worktrees" .gitignore 2>/dev/null; then
+    echo ".worktrees/" >> .gitignore
+fi
+```
+
+---
+
+## 🔄 Creation Steps
+
+### Step 1: Create Branch Name
+
+```bash
+# Format: feature/<descriptive-name>
+BRANCH_NAME="feature/$(echo "$FEATURE_DESC" | tr ' ' '-' | tr '[:upper:]' '[:lower:]')"
+```
+
+### Step 2: Create Worktree
+
+```bash
+# Create worktree with new branch
+git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
+```
+
+### Step 3: Navigate and Setup
+
+```bash
+cd ".worktrees/$BRANCH_NAME"
+
+# Run project setup (detect from project)
+if [ -f "package.json" ]; then
+    npm install
+elif [ -f "requirements.txt" ]; then
+    pip install -r requirements.txt
+elif [ -f "Cargo.toml" ]; then
+    cargo build
+fi
+```
+
+### Step 4: Verify Clean Baseline
+
+```bash
+# CRITICAL: Tests must pass BEFORE starting work
+npm test  # or equivalent
+
+# If tests fail, DO NOT proceed
+# Fix the baseline first
+```
+
+### Step 5: Report Location
+
+```
+✅ Worktree created: .worktrees/feature/my-feature
+📂 Branch: feature/my-feature
+🧪 Baseline: 45/45 tests passing
+```
+
+---
+
+## 🔧 Common Commands
+
+| Action | Command |
+|--------|---------|
+| List worktrees | `git worktree list` |
+| Create worktree | `git worktree add <path> -b <branch>` |
+| Remove worktree | `git worktree remove <path>` |
+| Prune stale | `git worktree prune` |
+
+---
+
+## ✅ Finishing a Worktree
+
+### When Work is Complete
+
+```bash
+# 1. Ensure all tests pass
+npm test
+
+# 2. Commit all changes
+git add .
+git commit -m "feat: description"
+
+# 3. Return to main checkout
+cd ../..
+
+# 4. Present options to user
+```
+
+### Options to Present
+
+| Option | Command | When to Use |
+|--------|---------|-------------|
+| **Merge** | `git merge feature/branch` | Ready to integrate |
+| **Create PR** | Push and create PR | Team review needed |
+| **Keep** | Do nothing | More work planned |
+| **Discard** | `git worktree remove .worktrees/feature/branch` | Experiment failed |
+
+---
+
+## ⚠️ Common Mistakes
+
+| Mistake | Consequence | Prevention |
+|---------|-------------|------------|
+| Skip ignore verification | Worktree committed to repo | Always check .gitignore |
+| Assume directory location | Wrong path, confusion | Check existing directories |
+| Proceed with failing tests | Bad baseline | Verify clean baseline |
+| Hardcode setup commands | Breaks on different projects | Detect from project files |
+| Forget to prune | Stale worktrees accumulate | `git worktree prune` regularly |
+
+---
+
+## 🔁 Integration with Other Skills
+
+| After Worktree Created | Use Skill |
+|------------------------|-----------|
+| Ready to plan work | `plan-writing` |
+| Implementing features | `tdd-workflow` |
+| Work complete | `verification-gate` |
+| Ready to merge | `git-worktrees` finish flow |
+
+---
+
+## 📋 Quick Reference
+
+```bash
+# Full workflow
+git worktree add .worktrees/feature-name -b feature/name
+cd .worktrees/feature-name
+npm install && npm test  # verify baseline
+# ... do work ...
+npm test  # verify completion
+cd ../..
+git merge feature/name  # or create PR
+git worktree remove .worktrees/feature-name
+git worktree prune
+```

package/.agent/skills/parallel-agents/SKILL.md

@@ -156,6 +156,95 @@ After all agents complete, synthesize:
 
 ---
 
+## 🔄 Two-Stage Review Pattern
+
+> **Adapted from obra/superpowers** - Quality gates per task
+
+### Overview
+
+For high-quality implementation, each task goes through TWO review stages:
+
+```
+Implementer → Spec Reviewer → Code Quality Reviewer → Next Task
+                    ↑                    ↑
+                    └────── Fix Loop ────┘
+```
+
+### Stage 1: Spec Compliance Review
+
+**Purpose:** Verify code matches specification exactly (no more, no less)
+
+**Template for Spec Reviewer:**
+```
+You are reviewing implementation for SPEC COMPLIANCE ONLY.
+
+Task Spec:
+[paste exact task specification]
+
+Implementation:
+[paste code or git diff]
+
+Review Checklist:
+□ All requirements in spec are implemented
+□ No extra features added (over-building)
+□ No requirements missing (under-building)
+□ Implementation matches spec intent
+
+Output: ✅ Spec Compliant OR ❌ Issues (list specific gaps)
+```
+
+### Stage 2: Code Quality Review
+
+**Purpose:** Ensure implementation is well-built (only after spec compliance passes)
+
+**Template for Code Quality Reviewer:**
+```
+You are reviewing implementation for CODE QUALITY ONLY.
+(Spec compliance already verified ✅)
+
+Code to Review:
+[paste code or git diff]
+
+Review Checklist:
+□ Clean code principles followed
+□ Error handling appropriate
+□ Performance acceptable
+□ Tests adequate
+□ No obvious security issues
+
+Output:
+- Strengths: [list]
+- Issues: [Critical/Important/Minor]
+- Verdict: ✅ Approved OR ❌ Issues to fix
+```
+
+### Review Flow Rules
+
+| Rule | Enforcement |
+|------|-------------|
+| Spec review FIRST | Never start code quality review before spec ✅ |
+| Fix loop required | If issues found, implementer fixes, reviewer re-reviews |
+| Both must pass | Cannot proceed to next task until both ✅ |
+| Same implementer fixes | Don't switch to different agent mid-task |
+
+### Integration with Orchestration
+
+```
+Use the backend-specialist agent to implement [task].
+
+[After implementation complete]
+
+Use the spec-reviewer to verify implementation matches [spec].
+
+[If spec review passes]
+
+Use the code-quality-reviewer to verify implementation quality.
+
+[Both pass → next task]
+```
+
+---
+
 ## Best Practices
 
 1. **Available agents** - 17 specialized agents can be orchestrated

package/.agent/skills/react-patterns/SKILL.md

@@ -7,6 +7,37 @@ allowed-tools: Read, Write, Edit, Glob, Grep
 # React Patterns
 
 > Principles for building production-ready React applications.
+> Based on patterns from Vercel Engineering (57 rules, 8 categories).
+
+---
+
+## 🎯 Performance Priority System
+
+| Priority | Category | Impact | Prefix | Reference |
+|----------|----------|--------|--------|-----------|
+| 1 | Eliminating Waterfalls | 🔴 CRITICAL | `async-` | [waterfall-patterns.md](waterfall-patterns.md) |
+| 2 | Bundle Size Optimization | 🔴 CRITICAL | `bundle-` | [bundle-patterns.md](bundle-patterns.md) |
+| 3 | Server-Side Performance | 🟠 HIGH | `server-` | [server-patterns.md](server-patterns.md) |
+| 4 | Client-Side Data Fetching | 🟡 MEDIUM-HIGH | `client-` | Below |
+| 5 | Re-render Optimization | 🟡 MEDIUM | `rerender-` | [rerender-patterns.md](rerender-patterns.md) |
+| 6 | Rendering Performance | 🟡 MEDIUM | `rendering-` | Below |
+| 7 | JavaScript Performance | 🟢 LOW-MEDIUM | `js-` | Below |
+| 8 | Advanced Patterns | 🟢 LOW | `advanced-` | Below |
+
+> 🔴 **Rule:** Fix CRITICAL issues first. Measure before optimizing MEDIUM/LOW.
+
+---
+
+## 📚 Modular Files
+
+Read ONLY the files relevant to your task:
+
+| File | When to Read |
+|------|--------------|
+| [waterfall-patterns.md](waterfall-patterns.md) | Async/await, data fetching |
+| [bundle-patterns.md](bundle-patterns.md) | Bundle size, imports |
+| [server-patterns.md](server-patterns.md) | RSC, caching, SSR |
+| [rerender-patterns.md](rerender-patterns.md) | State, memo, effects |
 
 ---
 

package/.agent/skills/react-patterns/bundle-patterns.md

@@ -0,0 +1,129 @@
+# Bundle Patterns (CRITICAL)
+
+> Bundle size directly impacts Time to Interactive. Critical for Core Web Vitals.
+
+---
+
+## bundle-barrel-imports
+
+**Import directly, avoid barrel files (index.ts/index.js).**
+
+```tsx
+// ❌ BAD: Barrel import pulls entire package into bundle
+import { Button } from '@/components';
+import { format } from 'date-fns';
+
+// ✅ GOOD: Direct import enables tree-shaking
+import { Button } from '@/components/Button';
+import { format } from 'date-fns/format';
+```
+
+| Library | Barrel-Free Import |
+|---------|-------------------|
+| date-fns | `date-fns/format` |
+| lodash | `lodash/debounce` |
+| @mui | `@mui/material/Button` |
+| lucide-react | `lucide-react/dist/esm/icons/menu` |
+
+---
+
+## bundle-dynamic-imports
+
+**Use next/dynamic for heavy components.**
+
+```tsx
+// ✅ Load only when needed
+const HeavyEditor = dynamic(() => import('./HeavyEditor'), {
+  loading: () => <Skeleton />,
+  ssr: false // If client-only
+});
+
+// ✅ Load on interaction
+const [showChart, setShowChart] = useState(false);
+const Chart = dynamic(() => import('./Chart'));
+
+{showChart && <Chart />}
+```
+
+| Component Type | Dynamic? |
+|----------------|----------|
+| Charts (recharts, chart.js) | ✅ Yes |
+| Rich text editors | ✅ Yes |
+| Code editors (Monaco) | ✅ Yes |
+| Modals/Dialogs | ⚠️ Consider |
+| Core UI | ❌ No |
+
+---
+
+## bundle-defer-third-party
+
+**Load analytics/logging after hydration.**
+
+```tsx
+// ✅ Load analytics after page is interactive
+useEffect(() => {
+  import('analytics').then(({ init }) => init());
+}, []);
+
+// ✅ Or use next/script with afterInteractive
+<Script 
+  src="https://analytics.com/script.js" 
+  strategy="afterInteractive" 
+/>
+```
+
+| Script Type | Strategy |
+|-------------|----------|
+| Analytics | `afterInteractive` |
+| Chat widgets | `lazyOnload` |
+| A/B testing | `beforeInteractive` |
+| Ads | `lazyOnload` |
+
+---
+
+## bundle-conditional
+
+**Load modules only when feature is activated.**
+
+```tsx
+// ✅ Load on user action
+const handleExport = async () => {
+  const { exportPDF } = await import('./export-utils');
+  exportPDF(data);
+};
+
+// ✅ Load based on feature flag
+const AdminPanel = featureFlags.admin 
+  ? dynamic(() => import('./AdminPanel'))
+  : null;
+```
+
+---
+
+## bundle-preload
+
+**Preload on hover/focus for perceived speed.**
+
+```tsx
+// ✅ Preload on hover
+<Link 
+  href="/dashboard"
+  onMouseEnter={() => router.prefetch('/dashboard')}
+>
+  Dashboard
+</Link>
+
+// ✅ Preload critical chunks
+<link rel="preload" href="/_next/static/chunks/heavy.js" as="script" />
+```
+
+---
+
+## Quick Checks
+
+| Signal | Action |
+|--------|--------|
+| Bundle > 200KB | Analyze with `@next/bundle-analyzer` |
+| `from 'library'` | Check for barrel-free alternative |
+| Heavy deps in layout | Move to dynamic import |
+| Third-party in `<head>` | Move to afterInteractive |