@neyugn/agent-kits 0.1.0

package/kits/coder/skills/brainstorming/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: brainstorming
+description: Socratic questioning protocol and user communication. Use for complex requests, new features, unclear requirements, or when deep understanding is needed before implementation. Includes progress reporting and error handling patterns.
+allowed-tools: Read, Write, Edit
+---
+
+# Brainstorming - Socratic Discovery Protocol
+
+> **Philosophy:** Understanding precedes implementation. Ask first, build second.
+
+---
+
+## 🎯 Core Principle: Never Assume
+
+```
+❌ WRONG: User says "add login" → Start coding auth flow
+✅ CORRECT: User says "add login" → Ask about auth provider, user types, session needs
+```
+
+**The Socratic Approach:**
+
+- Guide through questions, don't dictate solutions
+- Surface hidden assumptions
+- Challenge unclear requirements
+- Explore edge cases before they become bugs
+
+---
+
+## 🚦 When to Apply Socratic Gate
+
+### Decision Matrix
+
+| Request Type    | Clarity Level | Action                          |
+| --------------- | ------------- | ------------------------------- |
+| **New Feature** | Any           | ASK 3+ strategic questions      |
+| **Code Edit**   | Clear         | Confirm understanding, proceed  |
+| **Code Edit**   | Vague         | Ask impact questions first      |
+| **Bug Fix**     | Reproducible  | Investigate, minimal questions  |
+| **Bug Fix**     | Unclear       | Ask for reproduction steps      |
+| **Refactor**    | Any           | Ask about scope and constraints |
+
+### Question Triggers
+
+**Always ask questions when:**
+
+- User says "build", "create", "implement", "add feature"
+- Multiple valid interpretations exist
+- Request involves architecture decisions
+- Request affects multiple components
+- Trade-offs are not explicit
+
+**Skip questions when:**
+
+- User says "just fix this specific thing"
+- Request is purely mechanical (rename, format)
+- Context is already established in conversation
+- User explicitly says "don't ask, just do it"
+
+---
+
+## 🔑 Question Categories
+
+### 1. Purpose & Goal Questions
+
+**Uncover the "why":**
+
+```markdown
+- What problem does this solve for users?
+- What's the expected outcome when this works?
+- How will we know this feature is successful?
+- Is this for a specific user segment or all users?
+```
+
+### 2. Scope & Boundary Questions
+
+**Define the "what":**
+
+```markdown
+- What specifically should this include?
+- What explicitly should this NOT include?
+- Are there any time/budget constraints?
+- Is this a complete solution or MVP first?
+- What's the priority order if we can't do everything?
+```
+
+### 3. Context & Integration Questions
+
+**Understand the "where":**
+
+```markdown
+- How does this fit with existing features?
+- Are there similar patterns already in the codebase?
+- What systems does this need to integrate with?
+- Are there dependencies we should be aware of?
+```
+
+### 4. Edge Case & Failure Questions
+
+**Anticipate the "what if":**
+
+```markdown
+- What happens if [X condition] occurs?
+- How should we handle errors in this flow?
+- What's the expected behavior for edge cases?
+- Should we handle [unlikely but possible scenario]?
+```
+
+### 5. Trade-off Questions
+
+**Clarify the "how much":**
+
+```markdown
+- Performance vs code simplicity—which matters more here?
+- Should we build for scale now or optimize for speed to market?
+- Complete solution now or iterative enhancement?
+- Custom implementation or use existing library?
+```
+
+---
+
+## 📋 Question Templates by Scenario
+
+### New Feature Request
+
+```markdown
+Great, I want to make sure I build exactly what you need.
+
+**Understanding the goal:**
+
+1. What user problem does this solve?
+2. How will users discover/access this feature?
+
+**Scope check:** 3. What's the minimum version that would be useful? 4. Are there any "nice-to-haves" vs "must-haves"?
+
+**Technical clarification:** 5. Any performance requirements (response time, data volume)? 6. Any security considerations (auth, data sensitivity)?
+```
+
+### Bug Fix Request
+
+```markdown
+Before I investigate:
+
+1. Can you describe the expected vs actual behavior?
+2. Is this reproducible? What steps trigger it?
+3. When did this start happening? (recent change?)
+4. Does it affect all users or specific conditions?
+5. What's the severity/urgency?
+```
+
+### Refactoring Request
+
+```markdown
+To refactor effectively:
+
+1. What's the main goal? (Readability? Performance? Testability?)
+2. What's the scope boundary? (This file? This module? Entire feature?)
+3. Are there hidden consumers of this code we need to consider?
+4. Do we have test coverage to validate the refactor?
+5. Any patterns we should align with from other parts of the codebase?
+```
+
+### Architecture Decision
+
+```markdown
+This is an important decision. Let's explore:
+
+**Current State:**
+
+1. What's driving this architecture change?
+2. What problems exist with the current approach?
+
+**Future State:** 3. What are the key requirements for the new design? 4. What trade-offs are acceptable?
+
+**Constraints:** 5. Any technology restrictions or preferences? 6. Timeline or resource constraints?
+
+**Risks:** 7. What could go wrong with this change? 8. What's our rollback strategy?
+```
+
+---
+
+## 💬 Communication Patterns
+
+### Progress Reporting
+
+**For long tasks, report periodically:**
+
+```markdown
+🔄 **Progress Update:**
+
+**Completed:**
+
+- ✅ Created user authentication module
+- ✅ Added database schema
+
+**In Progress:**
+
+- 🔄 Implementing password reset flow
+
+**Remaining:**
+
+- ⏳ Email notification integration
+- ⏳ Testing and documentation
+
+**Estimated completion:** ~2 more steps
+```
+
+### Clarification Requests
+
+**When genuinely unclear:**
+
+```markdown
+🤔 **Quick clarification needed:**
+
+I want to proceed correctly, but I'm unsure about [specific thing].
+
+**Option A:** [Description] — Better for [use case]
+**Option B:** [Description] — Better for [use case]
+
+Which approach fits your needs?
+```
+
+### Error Handling Communication
+
+**When something goes wrong:**
+
+```markdown
+⚠️ **Issue Encountered:**
+
+**What happened:** [Brief description]
+
+**Why it happened:** [Root cause if known]
+
+**Options to proceed:**
+
+1. [Option with trade-off]
+2. [Different approach]
+3. [Need more info on X]
+
+What would you like to do?
+```
+
+### Confirmation Before Risky Actions
+
+**Before destructive or irreversible actions:**
+
+```markdown
+🛡️ **Confirmation Required:**
+
+I'm about to: [Describe action]
+
+**This will:**
+
+- [Effect 1]
+- [Effect 2]
+
+**This is irreversible / can be undone by [method]**
+
+Proceed? (yes/no)
+```
+
+---
+
+## 🔄 Iterative Discovery Pattern
+
+### When user provides spec-heavy answers
+
+```
+User provides detailed spec →
+  ↓
+Still ask 2-3 "Edge Case" questions:
+  - "What if [unlikely scenario]?"
+  - "Should we handle [error condition]?"
+  - "Is there a fallback for [dependency failure]?"
+  ↓
+Surface hidden assumptions before implementation
+```
+
+### Converging on Solution
+
+```
+1. Ask broad questions (Purpose, Scope)
+2. Ask specific questions (Technical details)
+3. Summarize understanding
+4. Propose approach
+5. Get confirmation
+6. Begin implementation
+```
+
+---
+
+## 🚨 Anti-Patterns
+
+| ❌ Don't                        | ✅ Do                                                |
+| ------------------------------- | ---------------------------------------------------- |
+| Ask 10+ questions at once       | Group into 3-5 most important                        |
+| Ask obvious questions           | Ask where there's genuine ambiguity                  |
+| Re-ask answered questions       | Read conversation context                            |
+| Block on every detail           | Make reasonable default assumptions for minor things |
+| Question simple requests        | Apply judgment on when questions add value           |
+| Ask then ignore answers         | Incorporate answers into your approach               |
+| Pretend to understand           | Admit confusion and ask for clarity                  |
+| Assume user knows best approach | Offer expert guidance with questions                 |
+
+---
+
+## 📋 Socratic Gate Checklist
+
+Before major implementation:
+
+```markdown
+## Pre-Implementation Review
+
+### Understanding (Must be clear)
+
+- [ ] I understand the user's goal
+- [ ] I understand the scope boundaries
+- [ ] I have asked about edge cases
+
+### Assumptions (Must be validated)
+
+- [ ] Technical assumptions stated and confirmed
+- [ ] Default behaviors agreed upon
+- [ ] Error handling approach confirmed
+
+### Risks (Must be acknowledged)
+
+- [ ] Breaking changes identified
+- [ ] Dependencies mapped
+- [ ] Rollback strategy exists
+
+### Ready to proceed?
+
+- [ ] User has confirmed approach
+- [ ] No critical questions remaining
+```
+
+---
+
+## 📊 Question Quality Metrics
+
+**Good questions are:**
+
+- **Specific** — Not vague or overly broad
+- **Actionable** — Answer directly informs implementation
+- **Prioritized** — Most important first
+- **Non-redundant** — Not already known from context
+
+**Question effectiveness:**
+
+| Question Type | When Valuable                       |
+| ------------- | ----------------------------------- |
+| Clarifying    | When terms are ambiguous            |
+| Probing       | When surface answer is insufficient |
+| Hypothetical  | When exploring edge cases           |
+| Comparative   | When choosing between options       |
+| Reflective    | When validating understanding       |
+
+---
+
+## 🔗 Related Skills
+
+| Need                         | Skill                  |
+| ---------------------------- | ---------------------- |
+| Writing implementation plans | `plan-writing`         |
+| Debugging with questions     | `systematic-debugging` |
+| Clean code standards         | `clean-code`           |
+
+---
+
+> **Remember:** The cost of asking one more question is minutes. The cost of building the wrong thing is days or weeks.

package/kits/coder/skills/brainstorming/assets/.gitkeep

@@ -0,0 +1 @@
+# Assets directory - add templates, images, etc.

package/kits/coder/skills/brainstorming/references/deep-dive.md

@@ -0,0 +1,21 @@
+# Reference Documentation for Brainstorming
+
+[TODO: Add detailed reference content here]
+
+## Overview
+
+[Detailed explanation of concepts]
+
+## Deep Dive Topics
+
+### Topic 1
+
+[Content]
+
+### Topic 2
+
+[Content]
+
+## Examples
+
+[Real-world examples]

package/kits/coder/skills/brainstorming/scripts/validate.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Example validator for brainstorming
+
+Usage:
+    python validate.py <project_path>
+"""
+
+import sys
+from pathlib import Path
+
+
+def validate(project_path: str) -> dict:
+    """Main validation logic"""
+    results = {
+        'errors': [],
+        'warnings': [],
+        'passed': []
+    }
+    
+    # TODO: Add validation logic
+    results['passed'].append('Placeholder validation passed')
+    
+    return results
+
+
+def print_results(results: dict):
+    """Pretty print results"""
+    print("\n🔍 Validation Results\n")
+    
+    if results['errors']:
+        print(f"❌ Errors ({len(results['errors'])})")
+        for error in results['errors']:
+            print(f"  - {error}")
+    
+    if results['warnings']:
+        print(f"\n⚠️  Warnings ({len(results['warnings'])})")
+        for warning in results['warnings']:
+            print(f"  - {warning}")
+    
+    if results['passed']:
+        print(f"\n✅ Passed ({len(results['passed'])})")
+        for passed in results['passed']:
+            print(f"  - {passed}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python validate.py <project_path>")
+        sys.exit(1)
+    
+    project_path = sys.argv[1]
+    results = validate(project_path)
+    print_results(results)
+    
+    sys.exit(1 if results['errors'] else 0)

package/kits/coder/skills/clean-code/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering. Use when writing any code, reviewing code, or establishing project conventions. Covers naming, function design, code structure, and AI coding style.
+allowed-tools: Read, Write, Edit
+version: 2.0
+priority: CRITICAL
+---
+
+# Clean Code - Pragmatic AI Coding Standards
+
+> **Philosophy:** Be **concise, direct, and solution-focused**. The user wants working code, not programming lessons.
+
+---
+
+## Core Principles
+
+| Principle     | Rule                                                       |
+| ------------- | ---------------------------------------------------------- |
+| **SRP**       | Single Responsibility - each function/class does ONE thing |
+| **DRY**       | Don't Repeat Yourself - extract duplicates, reuse          |
+| **KISS**      | Keep It Simple - simplest solution that works              |
+| **YAGNI**     | You Aren't Gonna Need It - don't build unused features     |
+| **Boy Scout** | Leave code cleaner than you found it                       |
+
+---
+
+## Naming Rules
+
+| Element       | Convention                                            |
+| ------------- | ----------------------------------------------------- |
+| **Variables** | Reveal intent: `userCount` not `n`                    |
+| **Functions** | Verb + noun: `getUserById()` not `user()`             |
+| **Booleans**  | Question form: `isActive`, `hasPermission`, `canEdit` |
+| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT`                    |
+| **Classes**   | PascalCase nouns: `UserService`, `PaymentGateway`     |
+| **Files**     | kebab-case or camelCase based on project convention   |
+
+> **Rule:** If you need a comment to explain a name, rename it.
+
+---
+
+## Function Rules
+
+| Rule                   | Description                           |
+| ---------------------- | ------------------------------------- |
+| **Small**              | Max 20 lines, ideally 5-10            |
+| **One Thing**          | Does one thing, does it well          |
+| **One Level**          | One level of abstraction per function |
+| **Few Args**           | Max 3 arguments, prefer 0-2           |
+| **No Side Effects**    | Don't mutate inputs unexpectedly      |
+| **Pure When Possible** | Same input → same output              |
+
+---
+
+## Code Structure
+
+| Pattern            | Apply                                     |
+| ------------------ | ----------------------------------------- |
+| **Guard Clauses**  | Early returns for edge cases              |
+| **Flat > Nested**  | Avoid deep nesting (max 2 levels)         |
+| **Composition**    | Small functions composed together         |
+| **Colocation**     | Keep related code close                   |
+| **Vertical Slice** | Feature files together, not by layer type |
+
+### Guard Clause Example
+
+```typescript
+// ❌ Nested
+function processUser(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasPermission) {
+        // actual logic 3 levels deep
+      }
+    }
+  }
+}
+
+// ✅ Guard Clauses
+function processUser(user) {
+  if (!user) return null;
+  if (!user.isActive) return null;
+  if (!user.hasPermission) return null;
+
+  // actual logic at top level
+}
+```
+
+---
+
+## AI Coding Style
+
+| Situation                 | Action                                     |
+| ------------------------- | ------------------------------------------ |
+| User asks for feature     | Write it directly                          |
+| User reports bug          | Fix it, don't explain first                |
+| No clear requirement      | Ask, don't assume                          |
+| Multiple valid approaches | Pick one, mention alternatives if critical |
+
+### Output Quality Rules
+
+| Rule                 | Description                                 |
+| -------------------- | ------------------------------------------- |
+| **No Preamble**      | Skip "Here's the code..." - just write code |
+| **No Postamble**     | Skip "This code does..." - let code speak   |
+| **Minimal Comments** | Only for complex/non-obvious business logic |
+| **Complete Code**    | No `// ... rest of code` placeholders       |
+| **Test Immediately** | Run/verify code before claiming complete    |
+
+---
+
+## Error Handling Patterns
+
+| Pattern            | When to Use                             |
+| ------------------ | --------------------------------------- |
+| **Return Early**   | Validation failures, missing data       |
+| **Throw Specific** | Domain errors, use custom error classes |
+| **Try/Catch**      | External calls, I/O operations          |
+| **Result Type**    | Complex operations, functional style    |
+
+### Error Handling Example
+
+```typescript
+// ❌ Generic
+throw new Error("Something went wrong");
+
+// ✅ Specific
+throw new UserNotFoundError(userId);
+throw new InsufficientFundsError(amount, balance);
+```
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Pattern                  | ✅ Fix                  |
+| --------------------------- | ----------------------- |
+| Comment every line          | Delete obvious comments |
+| Helper for one-liner        | Inline the code         |
+| Factory for 2 objects       | Direct instantiation    |
+| utils.ts with 1 function    | Put code where used     |
+| "First we import..."        | Just write code         |
+| Deep nesting (3+ levels)    | Guard clauses           |
+| Magic numbers               | Named constants         |
+| God functions (50+ lines)   | Split by responsibility |
+| Premature optimization      | Make it work first      |
+| Helper folder with 20 files | Colocate with features  |
+
+---
+
+## 🔴 Before Editing ANY File (THINK FIRST!)
+
+**Before changing a file, ask yourself:**
+
+| Question                        | Why                      |
+| ------------------------------- | ------------------------ |
+| **What imports this file?**     | They might break         |
+| **What does this file import?** | Interface changes        |
+| **What tests cover this?**      | Tests might fail         |
+| **Is this a shared component?** | Multiple places affected |
+
+**Quick Check:**
+
+```
+File to edit: UserService.ts
+└── Who imports this? → UserController.ts, AuthController.ts
+└── Do they need changes too? → Check function signatures
+```
+
+> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
+> 🔴 **Never leave broken imports or missing updates.**
+
+---
+
+## Summary
+
+| Do                     | Don't                      |
+| ---------------------- | -------------------------- |
+| Write code directly    | Write tutorials            |
+| Let code self-document | Add obvious comments       |
+| Fix bugs immediately   | Explain the fix first      |
+| Inline small things    | Create unnecessary files   |
+| Name things clearly    | Use abbreviations          |
+| Keep functions small   | Write 100+ line functions  |
+| Verify code works      | Claim done without testing |
+
+---
+
+## 🔴 Self-Check Before Completing (MANDATORY)
+
+**Before saying "task complete", verify:**
+
+| Check                     | Question                          |
+| ------------------------- | --------------------------------- |
+| ✅ **Goal met?**          | Did I do exactly what user asked? |
+| ✅ **Files edited?**      | Did I modify all necessary files? |
+| ✅ **Code works?**        | Did I test/verify the change?     |
+| ✅ **No errors?**         | Lint and TypeScript pass?         |
+| ✅ **Nothing forgotten?** | Any edge cases missed?            |
+
+> 🔴 **Rule:** If ANY check fails, fix it before completing.
+
+---
+
+## Decision Trees
+
+### When to Abstract?
+
+```
+Is code duplicated 3+ times?
+├── Yes → Extract function/component
+└── No → Is code complex AND reusable?
+    ├── Yes → Extract with clear interface
+    └── No → Keep inline
+```
+
+### When to Comment?
+
+```
+Is logic non-obvious?
+├── No → Don't comment
+└── Yes → Is it business logic or algorithm?
+    ├── Business logic → Comment the WHY
+    └── Algorithm → Link to reference + brief WHY
+```
+
+---
+
+## Related Skills
+
+| Need                 | Skill                  |
+| -------------------- | ---------------------- |
+| API design patterns  | `api-patterns`         |
+| Testing methodology  | `testing-patterns`     |
+| Systematic debugging | `systematic-debugging` |
+| Database design      | `database-design`      |
+
+---
+
+> **Remember:** The user wants working code, not a programming lesson. Be concise, be direct, be effective.

package/kits/coder/skills/clean-code/assets/.gitkeep

@@ -0,0 +1 @@
+# Assets directory - add templates, images, etc.

package/kits/coder/skills/clean-code/references/deep-dive.md

@@ -0,0 +1,21 @@
+# Reference Documentation for Clean Code
+
+[TODO: Add detailed reference content here]
+
+## Overview
+
+[Detailed explanation of concepts]
+
+## Deep Dive Topics
+
+### Topic 1
+
+[Content]
+
+### Topic 2
+
+[Content]
+
+## Examples
+
+[Real-world examples]