@musashishao/agent-kit 1.0.0

package/.agent/skills/architecture/trade-off-analysis.md

@@ -0,0 +1,77 @@
+# Trade-off Analysis & ADR
+
+> Document every architectural decision with trade-offs.
+
+## Decision Framework
+
+For EACH architectural component, document:
+
+```markdown
+## Architecture Decision Record
+
+### Context
+- **Problem**: [What problem are we solving?]
+- **Constraints**: [Team size, scale, timeline, budget]
+
+### Options Considered
+
+| Option | Pros | Cons | Complexity | When Valid |
+|--------|------|------|------------|-----------|
+| Option A | Benefit 1 | Cost 1 | Low | [Conditions] |
+| Option B | Benefit 2 | Cost 2 | High | [Conditions] |
+
+### Decision
+**Chosen**: [Option B]
+
+### Rationale
+1. [Reason 1 - tied to constraints]
+2. [Reason 2 - tied to requirements]
+
+### Trade-offs Accepted
+- [What we're giving up]
+- [Why this is acceptable]
+
+### Consequences
+- **Positive**: [Benefits we gain]
+- **Negative**: [Costs/risks we accept]
+- **Mitigation**: [How we'll address negatives]
+
+### Revisit Trigger
+- [When to reconsider this decision]
+```
+
+## ADR Template
+
+```markdown
+# ADR-[XXX]: [Decision Title]
+
+## Status
+Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]
+
+## Context
+[What problem? What constraints?]
+
+## Decision
+[What we chose - be specific]
+
+## Rationale
+[Why - tie to requirements and constraints]
+
+## Trade-offs
+[What we're giving up - be honest]
+
+## Consequences
+- **Positive**: [Benefits]
+- **Negative**: [Costs]
+- **Mitigation**: [How to address]
+```
+
+## ADR Storage
+
+```
+docs/
+└── architecture/
+    ├── adr-001-use-nextjs.md
+    ├── adr-002-postgresql-over-mongodb.md
+    └── adr-003-adopt-repository-pattern.md
+```

package/.agent/skills/bash-linux/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: bash-linux
+description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Bash Linux Patterns
+
+> Essential patterns for Bash on Linux/macOS.
+
+---
+
+## 1. Operator Syntax
+
+### Chaining Commands
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `;` | Run sequentially | `cmd1; cmd2` |
+| `&&` | Run if previous succeeded | `npm install && npm run dev` |
+| `\|\|` | Run if previous failed | `npm test \|\| echo "Tests failed"` |
+| `\|` | Pipe output | `ls \| grep ".js"` |
+
+---
+
+## 2. File Operations
+
+### Essential Commands
+
+| Task | Command |
+|------|---------|
+| List all | `ls -la` |
+| Find files | `find . -name "*.js" -type f` |
+| File content | `cat file.txt` |
+| First N lines | `head -n 20 file.txt` |
+| Last N lines | `tail -n 20 file.txt` |
+| Follow log | `tail -f log.txt` |
+| Search in files | `grep -r "pattern" --include="*.js"` |
+| File size | `du -sh *` |
+| Disk usage | `df -h` |
+
+---
+
+## 3. Process Management
+
+| Task | Command |
+|------|---------|
+| List processes | `ps aux` |
+| Find by name | `ps aux \| grep node` |
+| Kill by PID | `kill -9 <PID>` |
+| Find port user | `lsof -i :3000` |
+| Kill port | `kill -9 $(lsof -t -i :3000)` |
+| Background | `npm run dev &` |
+| Jobs | `jobs -l` |
+| Bring to front | `fg %1` |
+
+---
+
+## 4. Text Processing
+
+### Core Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `grep` | Search | `grep -rn "TODO" src/` |
+| `sed` | Replace | `sed -i 's/old/new/g' file.txt` |
+| `awk` | Extract columns | `awk '{print $1}' file.txt` |
+| `cut` | Cut fields | `cut -d',' -f1 data.csv` |
+| `sort` | Sort lines | `sort -u file.txt` |
+| `uniq` | Unique lines | `sort file.txt \| uniq -c` |
+| `wc` | Count | `wc -l file.txt` |
+
+---
+
+## 5. Environment Variables
+
+| Task | Command |
+|------|---------|
+| View all | `env` or `printenv` |
+| View one | `echo $PATH` |
+| Set temporary | `export VAR="value"` |
+| Set in script | `VAR="value" command` |
+| Add to PATH | `export PATH="$PATH:/new/path"` |
+
+---
+
+## 6. Network
+
+| Task | Command |
+|------|---------|
+| Download | `curl -O https://example.com/file` |
+| API request | `curl -X GET https://api.example.com` |
+| POST JSON | `curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL` |
+| Check port | `nc -zv localhost 3000` |
+| Network info | `ifconfig` or `ip addr` |
+
+---
+
+## 7. Script Template
+
+```bash
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined var, pipe fail
+
+# Colors (optional)
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+# Script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Functions
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+
+# Main
+main() {
+    log_info "Starting..."
+    # Your logic here
+    log_info "Done!"
+}
+
+main "$@"
+```
+
+---
+
+## 8. Common Patterns
+
+### Check if command exists
+
+```bash
+if command -v node &> /dev/null; then
+    echo "Node is installed"
+fi
+```
+
+### Default variable value
+
+```bash
+NAME=${1:-"default_value"}
+```
+
+### Read file line by line
+
+```bash
+while IFS= read -r line; do
+    echo "$line"
+done < file.txt
+```
+
+### Loop over files
+
+```bash
+for file in *.js; do
+    echo "Processing $file"
+done
+```
+
+---
+
+## 9. Differences from PowerShell
+
+| Task | PowerShell | Bash |
+|------|------------|------|
+| List files | `Get-ChildItem` | `ls -la` |
+| Find files | `Get-ChildItem -Recurse` | `find . -type f` |
+| Environment | `$env:VAR` | `$VAR` |
+| String concat | `"$a$b"` | `"$a$b"` (same) |
+| Null check | `if ($x)` | `if [ -n "$x" ]` |
+| Pipeline | Object-based | Text-based |
+
+---
+
+## 10. Error Handling
+
+### Set options
+
+```bash
+set -e          # Exit on error
+set -u          # Exit on undefined variable
+set -o pipefail # Exit on pipe failure
+set -x          # Debug: print commands
+```
+
+### Trap for cleanup
+
+```bash
+cleanup() {
+    echo "Cleaning up..."
+    rm -f /tmp/tempfile
+}
+trap cleanup EXIT
+```
+
+---
+
+> **Remember:** Bash is text-based. Use `&&` for success chains, `set -e` for safety, and quote your variables!

package/.agent/skills/behavioral-modes/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: behavioral-modes
+description: AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.
+allowed-tools: Read, Glob, Grep
+---
+
+# Behavioral Modes - Adaptive AI Operating Modes
+
+## Purpose
+This skill defines distinct behavioral modes that optimize AI performance for specific tasks. Modes change how the AI approaches problems, communicates, and prioritizes.
+
+---
+
+## Available Modes
+
+### 1. 🧠 BRAINSTORM Mode
+
+**When to use:** Early project planning, feature ideation, architecture decisions
+
+**Behavior:**
+- Ask clarifying questions before assumptions
+- Offer multiple alternatives (at least 3)
+- Think divergently - explore unconventional solutions
+- No code yet - focus on ideas and options
+- Use visual diagrams (mermaid) to explain concepts
+
+**Output style:**
+```
+"Let's explore this together. Here are some approaches:
+
+Option A: [description]
+  ✅ Pros: ...
+  ❌ Cons: ...
+
+Option B: [description]
+  ✅ Pros: ...
+  ❌ Cons: ...
+
+What resonates with you? Or should we explore a different direction?"
+```
+
+---
+
+### 2. ⚡ IMPLEMENT Mode
+
+**When to use:** Writing code, building features, executing plans
+
+**Behavior:**
+- **CRITICAL: Use `clean-code` skill standards** - concise, direct, no verbose explanations
+- Fast execution - minimize questions
+- Use established patterns and best practices
+- Write complete, production-ready code
+- Include error handling and edge cases
+- **NO tutorial-style explanations** - just code
+- **NO unnecessary comments** - let code self-document
+- **NO over-engineering** - solve the problem directly
+- **NO RUSHING** - Quality > Speed. Read ALL references before coding.
+
+**Output style:**
+```
+[Code block]
+
+[Brief summary, max 1-2 sentences]
+```
+
+**NOT:**
+```
+"Building [feature]...
+
+✓ Created [file1]
+✓ Created [file2]
+✓ Updated [file3]
+
+[long explanation]
+
+Run `npm run dev` to test."
+```
+
+---
+
+### 3. 🔍 DEBUG Mode
+
+**When to use:** Fixing bugs, troubleshooting errors, investigating issues
+
+**Behavior:**
+- Ask for error messages and reproduction steps
+- Think systematically - check logs, trace data flow
+- Form hypothesis → test → verify
+- Explain the root cause, not just the fix
+- Prevent future occurrences
+
+**Output style:**
+```
+"Investigating...
+
+🔍 Symptom: [what's happening]
+🎯 Root cause: [why it's happening]
+✅ Fix: [the solution]
+🛡️ Prevention: [how to avoid in future]
+```
+
+---
+
+### 4. 📋 REVIEW Mode
+
+**When to use:** Code review, architecture review, security audit
+
+**Behavior:**
+- Be thorough but constructive
+- Categorize by severity (Critical/High/Medium/Low)
+- Explain the "why" behind suggestions
+- Offer improved code examples
+- Acknowledge what's done well
+
+**Output style:**
+```
+## Code Review: [file/feature]
+
+### 🔴 Critical
+- [issue with explanation]
+
+### 🟠 Improvements
+- [suggestion with example]
+
+### 🟢 Good
+- [positive observation]
+```
+
+---
+
+### 5. 📚 TEACH Mode
+
+**When to use:** Explaining concepts, documentation, onboarding
+
+**Behavior:**
+- Explain from fundamentals
+- Use analogies and examples
+- Progress from simple to complex
+- Include practical exercises
+- Check understanding
+
+**Output style:**
+```
+## Understanding [Concept]
+
+### What is it?
+[Simple explanation with analogy]
+
+### How it works
+[Technical explanation with diagram]
+
+### Example
+[Code example with comments]
+
+### Try it yourself
+[Exercise or task]
+```
+
+---
+
+### 6. 🚀 SHIP Mode
+
+**When to use:** Production deployment, final polish, release preparation
+
+**Behavior:**
+- Focus on stability over features
+- Check for missing error handling
+- Verify environment configs
+- Run all tests
+- Create deployment checklist
+
+**Output style:**
+```
+## Pre-Ship Checklist
+
+### ✅ Code Quality
+- [ ] No TypeScript errors
+- [ ] ESLint passing
+- [ ] All tests passing
+
+### ✅ Security
+- [ ] No exposed secrets
+- [ ] Input validation complete
+
+### ✅ Performance
+- [ ] Bundle size acceptable
+- [ ] No console.logs
+
+### 🚀 Ready to deploy
+```
+
+---
+
+## Mode Detection
+
+The AI should automatically detect the appropriate mode based on:
+
+| Trigger | Mode |
+|---------|------|
+| "what if", "ideas", "options" | BRAINSTORM |
+| "build", "create", "add" | IMPLEMENT |
+| "not working", "error", "bug" | DEBUG |
+| "review", "check", "audit" | REVIEW |
+| "explain", "how does", "learn" | TEACH |
+| "deploy", "release", "production" | SHIP |
+
+---
+
+## Multi-Agent Collaboration Patterns (2025)
+
+Modern architectures optimized for agent-to-agent collaboration:
+
+### 1. 🔭 EXPLORE Mode
+**Role:** Discovery and Analysis (Explorer Agent)
+**Behavior:** Socratic questioning, deep-dive code reading, dependency mapping.
+**Output:** `discovery-report.json`, architectural visualization.
+
+### 2. 🗺️ PLAN-EXECUTE-CRITIC (PEC)
+Cyclic mode transitions for high-complexity tasks:
+1. **Planner:** Decomposes the task into atomic steps (`task.md`).
+2. **Executor:** Performs the actual coding (`IMPLEMENT`).
+3. **Critic:** Reviews the code, performs security and performance checks (`REVIEW`).
+
+### 3. 🧠 MENTAL MODEL SYNC
+Behavior for creating and loading "Mental Model" summaries to preserve context between sessions.
+
+---
+
+## Combining Modes
+
+---
+
+## Manual Mode Switching
+
+Users can explicitly request a mode:
+
+```
+/brainstorm new feature ideas
+/implement the user profile page
+/debug why login fails
+/review this pull request
+```

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

@@ -0,0 +1,163 @@
+---
+name: brainstorming
+description: Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements. Includes progress reporting and error handling.
+allowed-tools: Read, Glob, Grep
+---
+
+# Brainstorming & Communication Protocol
+
+> **MANDATORY:** Use for complex/vague requests, new features, updates.
+
+---
+
+## 🛑 SOCRATIC GATE (ENFORCEMENT)
+
+### When to Trigger
+
+| Pattern | Action |
+|---------|--------|
+| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions |
+| Complex feature or architecture | 🛑 Clarify before implementing |
+| Update/change request | 🛑 Confirm scope |
+| Vague requirements | 🛑 Ask purpose, users, constraints |
+
+### 🚫 MANDATORY: 3 Questions Before Implementation
+
+1. **STOP** - Do NOT start coding
+2. **ASK** - Minimum 3 questions:
+   - 🎯 Purpose: What problem are you solving?
+   - 👥 Users: Who will use this?
+   - 📦 Scope: Must-have vs nice-to-have?
+3. **WAIT** - Get response before proceeding
+
+---
+
+## 🧠 Dynamic Question Generation
+
+**⛔ NEVER use static templates.** Read `dynamic-questioning.md` for principles.
+
+### Core Principles
+
+| Principle | Meaning |
+|-----------|---------|
+| **Questions Reveal Consequences** | Each question connects to an architectural decision |
+| **Context Before Content** | Understand greenfield/feature/refactor/debug context first |
+| **Minimum Viable Questions** | Each question must eliminate implementation paths |
+| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs |
+
+### Question Generation Process
+
+```
+1. Parse request → Extract domain, features, scale indicators
+2. Identify decision points → Blocking vs. deferable
+3. Generate questions → Priority: P0 (blocking) > P1 (high-leverage) > P2 (nice-to-have)
+4. Format with trade-offs → What, Why, Options, Default
+```
+
+### Question Format (MANDATORY)
+
+```markdown
+### [PRIORITY] **[DECISION POINT]**
+
+**Question:** [Clear question]
+
+**Why This Matters:**
+- [Architectural consequence]
+- [Affects: cost/complexity/timeline/scale]
+
+**Options:**
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| A | [+] | [-] | [Use case] |
+
+**If Not Specified:** [Default + rationale]
+```
+
+**For detailed domain-specific question banks and algorithms**, see: `dynamic-questioning.md`
+
+---
+
+## Progress Reporting (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Transparency builds trust. Status must be visible and actionable.
+
+### Status Board Format
+
+| Agent | Status | Current Task | Progress |
+|-------|--------|--------------|----------|
+| [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |
+
+### Status Icons
+
+| Icon | Meaning | Usage |
+|------|---------|-------|
+| ✅ | Completed | Task finished successfully |
+| 🔄 | Running | Currently executing |
+| ⏳ | Waiting | Blocked, waiting for dependency |
+| ❌ | Error | Failed, needs attention |
+| ⚠️ | Warning | Potential issue, not blocking |
+
+---
+
+## Error Handling (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Errors are opportunities for clear communication.
+
+### Error Response Pattern
+
+```
+1. Acknowledge the error
+2. Explain what happened (user-friendly)
+3. Offer specific solutions with trade-offs
+4. Ask user to choose or provide alternative
+```
+
+### Error Categories
+
+| Category | Response Strategy |
+|----------|-------------------|
+| **Port Conflict** | Offer alternative port or close existing |
+| **Dependency Missing** | Auto-install or ask permission |
+| **Build Failure** | Show specific error + suggested fix |
+| **Unclear Error** | Ask for specifics: screenshot, console output |
+
+---
+
+## Completion Message (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Celebrate success, guide next steps.
+
+### Completion Structure
+
+```
+1. Success confirmation (celebrate briefly)
+2. Summary of what was done (concrete)
+3. How to verify/test (actionable)
+4. Next steps suggestion (proactive)
+```
+
+---
+
+## Communication Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Concise** | No unnecessary details, get to point |
+| **Visual** | Use emojis (✅🔄⏳❌) for quick scanning |
+| **Specific** | "~2 minutes" not "wait a bit" |
+| **Alternatives** | Offer multiple paths when stuck |
+| **Proactive** | Suggest next step after completion |
+
+---
+
+## Anti-Patterns (AVOID)
+
+| Anti-Pattern | Why |
+|--------------|-----|
+| Jumping to solutions before understanding | Wastes time on wrong problem |
+| Assuming requirements without asking | Creates wrong output |
+| Over-engineering first version | Delays value delivery |
+| Ignoring constraints | Creates unusable solutions |
+| "I think" phrases | Uncertainty → Ask instead |
+
+---