@musashishao/agent-kit 1.0.0 → 1.1.0

package/.agent/skills/problem-solving/simplification-cascades.md

@@ -0,0 +1,321 @@
+---
+name: simplification-cascades
+parent: problem-solving
+description: Find one insight that eliminates multiple components. "If this is true, we don't need X, Y, or Z."
+---
+
+# Simplification Cascades
+
+> The best solution is the one that makes other solutions unnecessary.
+
+## When to Use
+
+- Solution feels overcomplicated
+- Too many edge cases to handle
+- Architecture is getting messy
+- "Spaghetti" feeling
+- Looking for elegant solutions
+
+---
+
+## The Process
+
+### Step 1: Map Current Complexity
+
+List all components of your current solution:
+
+```
+Feature: User Permissions System
+
+Components:
+├── Role definitions (5 files)
+├── Permission checks (23 places in code)
+├── Role assignment UI (3 screens)
+├── Role inheritance logic
+├── Permission caching layer
+├── Audit logging
+├── Admin override system
+├── Permission migration scripts
+├── Role hierarchy validation
+└── Permission conflict resolution
+
+Count: 10+ components
+Files: 15+
+Complexity: HIGH
+```
+
+### Step 2: Ask "What If" Questions
+
+Challenge the need for each component:
+
+```
+"What if there were only 2 roles?"
+├── Most systems really need: Admin vs Member
+├── 90% of role complexity goes unused
+└── Would we still need inheritance? NO
+
+"What if permissions were at resource level?"
+├── Instead of: user → role → permission
+├── Just: user → resource (access/no access)
+└── Would we still need the matrix? NO
+
+"What if we removed inheritance?"
+├── Explicit beats implicit
+├── Copy permissions instead of inherit
+└── Would we still need conflict resolution? NO
+```
+
+### Step 3: Find the Cascade Effect
+
+One insight that eliminates multiple things:
+
+```
+WINNING INSIGHT: "We only need 2 roles"
+
+ELIMINATION CASCADE:
+┌────────────────────────────────────────────────────────┐
+│ Insight: Only 2 roles (Admin, Member)                 │
+├────────────────────────────────────────────────────────┤
+│ ✅ ELIMINATE: Role inheritance logic                   │
+│ ✅ ELIMINATE: Complex permission matrix                │
+│ ✅ ELIMINATE: Role hierarchy validation                │
+│ ✅ ELIMINATE: Permission conflict resolution           │
+│ ✅ SIMPLIFY: Role UI → simple dropdown                 │
+│ ✅ SIMPLIFY: Permission checks → isAdmin() helper      │
+│ ✅ SIMPLIFY: Audit → just log role changes             │
+│ ⚠️ KEEP: Resource-level exceptions (rare)             │
+└────────────────────────────────────────────────────────┘
+
+RESULT:
+├── Components: 10 → 3 (70% reduction)
+├── Files: 15 → 5 (67% reduction)
+├── Maintenance: almost eliminated
+└── New developer onboarding: "Admins can do everything"
+```
+
+### Step 4: Validate the Simplification
+
+```
+VALIDATION CHECKLIST:
+
+□ Does this cover 90% of use cases?
+  → YES, most users are just "members"
+
+□ What's lost?
+  → Granular permissions (used by 0.1% of orgs)
+
+□ Can we add back if needed?
+  → YES, as a "Pro plan" feature
+
+□ What's the migration path?
+  → Map all existing roles to Admin/Member
+  → Exceptions become explicit resource access
+
+□ Is this reversible?
+  → YES, we keep the data, just simplify logic
+
+DECISION: ✅ PROCEED
+```
+
+---
+
+## Simplification Patterns
+
+### Pattern 1: Reduce Options
+
+```
+BEFORE: 5 notification channels
+├── Email, SMS, Push, Slack, Webhook
+├── Each needs: setup, templates, testing, monitoring
+└── Complexity: 5x everything
+
+ASK: "What percentage use each?"
+├── Email: 95%
+├── Push: 70%
+├── Others: <10% each
+
+AFTER: 2 notification channels
+├── Email + Push only
+├── Others get Webhook (DIY)
+└── Complexity: 2x + simple webhook
+```
+
+### Pattern 2: Remove Flexibility
+
+```
+BEFORE: Configurable everything
+├── Custom fields
+├── Custom workflows
+├── Custom permissions
+├── Custom integrations
+└── Complexity: INFINITE edge cases
+
+ASK: "What if nothing was configurable?"
+├── Opinionated: We decide the best way
+├── Simpler: No config UI needed
+├── Faster: No "how do I configure X?" support
+└── Better: Our way is well-tested
+
+AFTER: Opinionated defaults
+├── 3 fixed workflows (most common)
+├── 5 standard permissions
+├── Official integrations only
+└── Complexity: FINITE, tested, documented
+```
+
+### Pattern 3: Make It Manual
+
+```
+BEFORE: Automated sync system
+├── Real-time sync
+├── Conflict resolution
+├── Retry logic
+├── Status monitoring
+├── Failure alerts
+└── Complexity: distributed systems hard
+
+ASK: "What if users just clicked refresh?"
+├── Sync on demand
+├── User can see if outdated
+├── Simple "last updated" timestamp
+├── No background jobs
+└── No conflict scenarios
+
+AFTER: Manual refresh
+├── "Sync Now" button
+├── Last synced timestamp
+└── Complexity: almost zero
+```
+
+### Pattern 4: Accept Tradeoffs
+
+```
+BEFORE: Handle all edge cases
+├── 50 edge cases identified
+├── Each needs handling logic
+├── Each needs testing
+├── Each needs documentation
+└── Complexity: grows forever
+
+ASK: "What if we just didn't handle rare cases?"
+├── Focus on 80% of users
+├── Edge cases get manual process
+├── Support handles exceptions
+└── Document known limitations
+
+AFTER: Graceful limitations
+├── "For large imports, contact support"
+├── "Bulk operations limited to 100 items"
+├── Edge cases: 5 clear limitations
+└── Complexity: bounded, maintained
+```
+
+---
+
+## Simplification Questions
+
+| When you see... | Ask... |
+|-----------------|--------|
+| Multiple similar components | "Can we consolidate to one?" |
+| Configurable options | "What if we picked for them?" |
+| Real-time sync | "What if it was on-demand?" |
+| Edge case handling | "What if we documented limitations instead?" |
+| Inheritance/hierarchy | "What if everything was flat?" |
+| Caching layer | "What if we just made it fast?" |
+| Background jobs | "What if it was synchronous?" |
+| Role-based access | "What if there were only 2 roles?" |
+| Flexible schema | "What if schema was fixed?" |
+| Multiple auth methods | "What if we only supported one?" |
+
+---
+
+## The Cascade Effect Template
+
+```
+INSIGHT: [Your simplifying insight]
+
+If this is true, we can:
+├── ELIMINATE: [Component 1]
+├── ELIMINATE: [Component 2]
+├── SIMPLIFY: [Component 3] → [Simple version]
+├── SIMPLIFY: [Component 4] → [Simple version]
+└── KEEP: [Only what's truly needed]
+
+REDUCTION:
+├── Components: [X] → [Y] ([Z]% reduction)
+├── Complexity: [Description of improvement]
+└── Maintenance: [Description of improvement]
+```
+
+---
+
+## Practice Exercise
+
+### Your Complex System:
+> _______________________________________________
+
+### Current Components (list all):
+1. _______________________________________________
+2. _______________________________________________
+3. _______________________________________________
+4. _______________________________________________
+5. _______________________________________________
+6. _______________________________________________
+
+### Simplification Questions:
+- What if we only supported 2 options?
+- What if users did it manually?
+- What if we didn't handle edge cases?
+- What if nothing was configurable?
+
+### Your Winning Insight:
+> _______________________________________________
+
+### What Gets Eliminated:
+1. _______________________________________________
+2. _______________________________________________
+3. _______________________________________________
+
+### Reduction:
+- Components: ___ → ___
+- Estimated complexity reduction: ___%
+
+---
+
+## Quick Reference
+
+```
+SIMPLIFICATION IN 60 SECONDS:
+
+1. List all components:
+   → "This system has [A], [B], [C], [D]..."
+
+2. Challenge each with "What if...":
+   → "What if we only had 2 options?"
+   → "What if users did this themselves?"
+
+3. Find the cascade:
+   → "If [insight], then we don't need [X, Y, Z]"
+
+4. Validate:
+   → "Does this cover 90% of cases?"
+   → "Is what we lose acceptable?"
+
+5. Execute:
+   → Remove the complexity with confidence
+```
+
+---
+
+## Warning Signs You Need Simplification
+
+- "It's complicated, but necessary"
+- "We need a diagram to explain it"
+- "Only [person] understands how it works"
+- "We'll document it later"
+- "This edge case requires..."
+- Adding more code to fix bugs in complexity
+
+---
+
+> **Remember:** The goal isn't to oversimplify—it's to find the insight that makes complexity unnecessary. Often the best code is the code you don't have to write.

package/.agent/skills/problem-solving/when-stuck.md

@@ -0,0 +1,146 @@
+---
+name: when-stuck
+parent: problem-solving
+description: Dispatcher to route you to the right problem-solving technique based on your specific type of stuck-ness.
+---
+
+# When Stuck - Problem Dispatcher
+
+> Use this when you don't know which problem-solving technique to use.
+
+## Quick Assessment
+
+Answer honestly: **What type of stuck am I?**
+
+---
+
+## Decision Tree
+
+```
+START HERE
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I don't know where to start"                            │
+│                                                             │
+│   → INVERSION EXERCISE                                      │
+│     Start from the end goal, work backwards                 │
+│     Question: "What does success look like?"               │
+│     Then: "What's the step right before success?"          │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I've tried everything, nothing works"                   │
+│                                                             │
+│   → COLLISION ZONE THINKING                                │
+│     Force unrelated concepts together                       │
+│     Question: "What if this worked like [random domain]?"  │
+│     Pick: restaurants, video games, airports, theme parks  │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "The solution is getting too complex"                    │
+│                                                             │
+│   → SIMPLIFICATION CASCADES                                │
+│     Find the one insight that eliminates complexity         │
+│     Question: "What single change removes 3+ components?"  │
+│     Start: List all components, find the linchpin          │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I can't see the full picture"                           │
+│                                                             │
+│   → META-PATTERN RECOGNITION                               │
+│     Find patterns that appear in 3+ domains                 │
+│     Question: "What domains have solved similar problems?" │
+│     Look: Nature, business, physics, biology               │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "My assumptions might be wrong"                          │
+│                                                             │
+│   → INVERSION EXERCISE                                      │
+│     Flip every assumption and explore                       │
+│     Question: "What if the opposite were true?"            │
+│     Start: List 5 assumptions, invert each                 │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I need to validate my approach"                         │
+│                                                             │
+│   → SCALE GAME                                              │
+│     Test at extreme scales to reveal hidden constraints     │
+│     Question: "What happens at 1000x? At 0.001x?"          │
+│     Check: What breaks? What's revealed?                   │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I'm blocked by external factors"                        │
+│                                                             │
+│   → SEPARATE: Constraints vs Assumptions                   │
+│     Real constraint: Cannot be changed (physics, law)       │
+│     Assumed constraint: "We've always done it this way"    │
+│     Question: "Who decided this rule?"                     │
+└─────────────────────────────────────────────────────────────┘
+    │ (not this)
+    ▼
+┌─────────────────────────────────────────────────────────────┐
+│   "I'm overthinking this"                                  │
+│                                                             │
+│   → SIMPLE ACTION                                          │
+│     Take the smallest possible action                       │
+│     Question: "What's a 5-minute experiment?"              │
+│     Do: Build the smallest thing that teaches you          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Protocol
+
+### Step 1: Name Your Block
+Write ONE sentence about why you're stuck:
+> "I'm stuck because _______________"
+
+### Step 2: Match to Type
+Look at the decision tree above. Which resonates?
+
+### Step 3: Apply Framework
+Go to that framework and follow its process.
+
+### Step 4: Time-box
+Give yourself 15-30 minutes with one framework. If still stuck, try the next one.
+
+---
+
+## Emergency Unstuck (2 minutes)
+
+If you don't have time for a full framework:
+
+1. **Write down the problem** in one sentence
+2. **Invert it:** What if the opposite were true?
+3. **Scale it:** What if this was 1000x bigger? 1000x smaller?
+4. **Random collision:** What if this worked like a restaurant?
+5. **Pick the most interesting insight** and explore for 5 minutes
+
+---
+
+## Framework Quick Links
+
+| Framework | Best For | Time Needed |
+|-----------|----------|-------------|
+| [Inversion](inversion-exercise.md) | Wrong assumptions, no starting point | 15 min |
+| [Collision Zone](collision-zone-thinking.md) | Need creativity, tried everything | 20 min |
+| [Scale Game](scale-game.md) | Validation, hidden constraints | 15 min |
+| [Pattern Recognition](meta-pattern-recognition.md) | Complex systems, wisdom needed | 30 min |
+| [Simplification](simplification-cascades.md) | Overcomplicated, need elegance | 20 min |
+
+---
+
+> **Pro Tip:** Keep a "stuck journal." Every time you get stuck and unstuck, note which framework helped. You'll learn your patterns.

package/.agent/workflows/context.md

@@ -0,0 +1,47 @@
+---
+description: Auto-generate optimized context for complex tasks using Context Engineering strategies.
+---
+
+# Context Optimization Workflow
+
+This workflow automates the "Context Engineering" process. It analyzes your request, maps the project structure, summarizes relevant files, and wraps everything in a high-performance XML prompt structure for the AI.
+
+**Trigger:** `/context [your task description]`
+
+## Steps
+
+1.  **Analyze Intent:**
+    Take the user's task description ("{{task_description}}") and identify key domains (e.g., frontend, auth, database).
+
+2.  **Generate Repo Map:**
+    // turbo
+    Run the repo mapper to see the current structure.
+    `python3 .agent/skills/context-engineering/scripts/repo_mapper.py .`
+
+3.  **Construct Optimized Prompt:**
+    Based on the repo map and task, construct the following `Advanced Context` block.
+    
+    **(Internal Instruction to AI):**
+    > You must now act as a Context Engineer. Do NOT just answer the user yet.
+    > Instead, OUTPUT a structured plan and code analysis using the gathered context.
+    > Use the `<thinking>` tag to analyze the Repo Map below.
+    > If the user's task matches specific files in the map, read them using `view_file`.
+    
+    **Structure to enforce:**
+    ```xml
+    <system_role>Senior Architect</system_role>
+    <project_context>
+        [Insert Output from Step 2 here]
+    </project_context>
+    <user_task>
+        {{task_description}}
+    </user_task>
+    <instruction>
+        1. Analyze the project structure above.
+        2. Identify ensuring files that need to be read or modified.
+        3. Proceed with solving the user's task using Chain-of-Thought (<thinking> tags).
+    </instruction>
+    ```
+
+4.  **Execute:**
+    Proceed to solve the user's request using the heightened context awareness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@musashishao/agent-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
   "main": "index.js",
   "bin": {