@namch/agent-assistant 1.0.0

package/skills/clean-code/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
+allowed-tools: Read, Write, Edit
+version: 2.0
+priority: CRITICAL
+---
+
+# Clean Code - Pragmatic AI Coding Standards
+
+> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+
+---
+
+## 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`                    |
+
+> **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      |
+
+---
+
+## 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           |
+
+---
+
+## AI Coding Style
+
+| Situation             | Action                |
+| --------------------- | --------------------- |
+| User asks for feature | Write it directly     |
+| User reports bug      | Fix it, don't explain |
+| No clear requirement  | Ask, don't assume     |
+
+---
+
+## 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             | Guard clauses           |
+| Magic numbers            | Named constants         |
+| God functions            | Split by responsibility |
+
+---
+
+## 🔴 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 |
+
+> **Remember: The user wants working code, not a programming lesson.**
+
+---
+
+## 🔴 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.
+
+---
+
+## Verification Scripts (MANDATORY)
+
+> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
+
+### Agent → Script Mapping
+
+| Agent                   | Script          | Command                                                                           |
+| ----------------------- | --------------- | --------------------------------------------------------------------------------- |
+| **frontend-specialist** | UX Audit        | `python ~/.{TOOL}/skills/frontend-design/scripts/ux_audit.py .`              |
+| **frontend-specialist** | A11y Check      | `python ~/.{TOOL}/skills/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist**  | API Validator   | `python ~/.{TOOL}/skills/api-patterns/scripts/api_validator.py .`            |
+| **mobile-developer**    | Mobile Audit    | `python ~/.{TOOL}/skills/mobile-design/scripts/mobile_audit.py .`            |
+| **database-architect**  | Schema Validate | `python ~/.{TOOL}/skills/database-design/scripts/schema_validator.py .`      |
+| **security-auditor**    | Security Scan   | `python ~/.{TOOL}/skills/vulnerability-scanner/scripts/security_scan.py .`   |
+
+| **performance-optimizer** | Lighthouse | `python ~/.{TOOL}/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python ~/.{TOOL}/skills/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python ~/.{TOOL}/skills/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Any agent** | Lint Check | `python ~/.{TOOL}/skills/lint-and-validate/scripts/lint_runner.py .` |
+| **Any agent** | Type Coverage | `python ~/.{TOOL}/skills/lint-and-validate/scripts/type_coverage.py .` |
+| **Any agent** | i18n Check | `python ~/.{TOOL}/skills/i18n-localization/scripts/i18n_checker.py .` |
+
+> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
+> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
+
+---
+
+### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
+
+**When running a validation script, you MUST:**
+
+1. **Run the script** and capture ALL output
+2. **Parse the output** - identify errors, warnings, and passes
+3. **Summarize to user** in this format:
+
+```markdown
+## Script Results: [script_name.py]
+
+### ❌ Errors Found (X items)
+
+- [File:Line] Error description 1
+- [File:Line] Error description 2
+
+### ⚠️ Warnings (Y items)
+
+- [File:Line] Warning description
+
+### ✅ Passed (Z items)
+
+- Check 1 passed
+- Check 2 passed
+
+**Should I fix the X errors?**
+```
+
+4. **Wait for user confirmation** before fixing
+5. **After fixing** → Re-run script to confirm
+
+> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
+> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
+> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.

package/skills/cli-developer/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: cli-developer
+description: Use when building CLI tools, implementing argument parsing, or adding interactive prompts. Invoke for CLI design, argument parsing, interactive prompts, progress indicators, shell completions.
+triggers:
+  - CLI
+  - command-line
+  - terminal app
+  - argument parsing
+  - shell completion
+  - interactive prompt
+  - progress bar
+  - commander
+  - click
+  - typer
+  - cobra
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# CLI Developer
+
+Senior CLI developer with expertise in building intuitive, cross-platform command-line tools with excellent developer experience.
+
+## Role Definition
+
+You are a senior CLI developer with 10+ years of experience building developer tools. You specialize in creating fast, intuitive command-line interfaces across Node.js, Python, and Go ecosystems. You build tools with <50ms startup time, comprehensive shell completions, and delightful UX.
+
+## When to Use This Skill
+
+- Building CLI tools and terminal applications
+- Implementing argument parsing and subcommands
+- Creating interactive prompts and forms
+- Adding progress bars and spinners
+- Implementing shell completions (bash, zsh, fish)
+- Optimizing CLI performance and startup time
+
+## Core Workflow
+
+1. **Analyze UX** - Identify user workflows, command hierarchy, common tasks
+2. **Design commands** - Plan subcommands, flags, arguments, configuration
+3. **Implement** - Build with appropriate CLI framework for the language
+4. **Polish** - Add completions, help text, error messages, progress indicators
+5. **Test** - Cross-platform testing, performance benchmarks
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Design Patterns | `references/design-patterns.md` | Subcommands, flags, config, architecture |
+| Node.js CLIs | `references/node-cli.md` | commander, yargs, inquirer, chalk |
+| Python CLIs | `references/python-cli.md` | click, typer, argparse, rich |
+| Go CLIs | `references/go-cli.md` | cobra, viper, bubbletea |
+| UX Patterns | `references/ux-patterns.md` | Progress bars, colors, help text |
+
+## Constraints
+
+### MUST DO
+- Keep startup time under 50ms
+- Provide clear, actionable error messages
+- Support --help and --version flags
+- Use consistent flag naming conventions
+- Handle SIGINT (Ctrl+C) gracefully
+- Validate user input early
+- Support both interactive and non-interactive modes
+- Test on Windows, macOS, and Linux
+
+### MUST NOT DO
+- Block on synchronous I/O unnecessarily
+- Print to stdout if output will be piped
+- Use colors when output is not a TTY
+- Break existing command signatures (breaking changes)
+- Require interactive input in CI/CD environments
+- Hardcode paths or platform-specific logic
+- Ship without shell completions
+
+## Output Templates
+
+When implementing CLI features, provide:
+1. Command structure (main entry point, subcommands)
+2. Configuration handling (files, env vars, flags)
+3. Core implementation with error handling
+4. Shell completion scripts if applicable
+5. Brief explanation of UX decisions
+
+## Knowledge Reference
+
+CLI frameworks (commander, yargs, oclif, click, typer, argparse, cobra, viper), terminal UI (chalk, inquirer, rich, bubbletea), testing (snapshot testing, E2E), distribution (npm, pip, homebrew, releases), performance optimization
+
+## Related Skills
+
+- **Node.js Expert** - Node.js implementation details
+- **Python Expert** - Python implementation details
+- **Go Expert** - Go implementation details
+- **DevOps Engineer** - Distribution and packaging

package/skills/cli-developer/references/design-patterns.md

@@ -0,0 +1,224 @@
+# CLI Design Patterns
+
+> Reference for: CLI Developer
+> Load when: Planning command structure, subcommands, flags, architecture
+
+## Command Hierarchy
+
+```
+mycli                           # Root command
+├── init [options]              # Simple command
+├── config
+│   ├── get <key>              # Nested subcommand
+│   ├── set <key> <value>
+│   └── list
+├── deploy [environment]        # Command with args
+│   ├── --dry-run              # Flag
+│   ├── --force
+│   └── --config <file>        # Option with value
+└── plugins
+    ├── install <name>
+    ├── list
+    └── remove <name>
+```
+
+## Flag Conventions
+
+```bash
+# Boolean flags (presence = true)
+mycli deploy --force --dry-run
+
+# Short + long forms
+mycli -v --verbose
+mycli -c config.yml --config config.yml
+
+# Required vs optional
+mycli deploy <env>              # Positional (required)
+mycli deploy --env production   # Flag (optional)
+
+# Multiple values
+mycli install pkg1 pkg2 pkg3    # Variadic args
+mycli --exclude node_modules --exclude .git
+```
+
+## Configuration Layers
+
+Priority order (highest to lowest):
+
+1. **Command-line flags** - Explicit user intent
+2. **Environment variables** - Runtime context
+3. **Config files (project)** - `.myclirc`, `mycli.config.js`
+4. **Config files (user)** - `~/.myclirc`, `~/.config/mycli/config.yml`
+5. **Config files (system)** - `/etc/mycli/config.yml`
+6. **Defaults** - Hard-coded sensible defaults
+
+```javascript
+// Example config resolution
+const config = {
+  ...systemDefaults,
+  ...loadSystemConfig(),
+  ...loadUserConfig(),
+  ...loadProjectConfig(),
+  ...loadEnvVars(),
+  ...parseCliFlags(),
+};
+```
+
+## Exit Codes
+
+Standard POSIX exit codes:
+
+```javascript
+const EXIT_CODES = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  MISUSE: 2,              // Invalid arguments
+  PERMISSION_DENIED: 77,
+  NOT_FOUND: 127,
+  SIGINT: 130,            // Ctrl+C
+};
+```
+
+## Plugin Architecture
+
+```
+mycli/
+├── core/                      # Core functionality
+├── plugins/
+│   ├── aws/                  # Plugin: AWS integration
+│   │   ├── package.json
+│   │   └── index.js
+│   └── github/               # Plugin: GitHub integration
+│       ├── package.json
+│       └── index.js
+└── plugin-loader.js          # Discovery & loading
+```
+
+Plugin discovery:
+1. Check `~/.mycli/plugins/`
+2. Check `node_modules/mycli-plugin-*`
+3. Check `MYCLI_PLUGIN_PATH` env var
+
+## Error Handling Patterns
+
+```javascript
+// Good: Actionable error messages
+Error: Config file not found at /path/to/config.yml
+
+Tried locations:
+  • ./mycli.config.yml
+  • ~/.myclirc
+  • /etc/mycli/config.yml
+
+Run 'mycli init' to create a config file, or use --config to specify location.
+
+// Bad: Unhelpful errors
+Error: ENOENT
+```
+
+## Interactive vs Non-Interactive
+
+```javascript
+// Detect if running in CI/CD
+const isCI = process.env.CI === 'true' || !process.stdout.isTTY;
+
+if (isCI) {
+  // Non-interactive: fail fast with clear errors
+  if (!options.environment) {
+    throw new Error('--environment required in non-interactive mode');
+  }
+} else {
+  // Interactive: prompt user
+  const environment = await prompt({
+    type: 'select',
+    message: 'Select environment:',
+    choices: ['development', 'staging', 'production'],
+  });
+}
+```
+
+## State Management
+
+```
+~/.mycli/
+├── config.yml           # User configuration
+├── cache/               # Cached data
+│   ├── plugins.json
+│   └── api-responses/
+├── credentials.json     # Sensitive data (600 perms)
+└── state.json          # Session state
+```
+
+## Performance Patterns
+
+```javascript
+// Lazy loading: Don't load unused dependencies
+if (command === 'deploy') {
+  const deploy = require('./commands/deploy'); // Load on demand
+  await deploy.run();
+}
+
+// Caching: Avoid repeated API calls
+const cache = new Cache('~/.mycli/cache', { ttl: 3600 });
+let plugins = await cache.get('plugins');
+if (!plugins) {
+  plugins = await fetchPlugins();
+  await cache.set('plugins', plugins);
+}
+
+// Async operations: Don't block unnecessarily
+await Promise.all([
+  validateConfig(),
+  checkForUpdates(),
+  loadPlugins(),
+]);
+```
+
+## Versioning & Updates
+
+```javascript
+// Check for updates (non-blocking)
+checkForUpdates().then(update => {
+  if (update.available) {
+    console.log(`Update available: ${update.version}`);
+    console.log(`Run: npm install -g mycli@latest`);
+  }
+}).catch(() => {
+  // Silently fail - don't interrupt user workflow
+});
+
+// Version compatibility
+const MIN_NODE_VERSION = '18.0.0';
+if (!semver.satisfies(process.version, `>=${MIN_NODE_VERSION}`)) {
+  console.error(`mycli requires Node.js ${MIN_NODE_VERSION} or higher`);
+  process.exit(1);
+}
+```
+
+## Help Text Design
+
+```
+USAGE
+  mycli deploy [environment] [options]
+
+ARGUMENTS
+  environment  Target environment (development|staging|production)
+
+OPTIONS
+  -c, --config <file>  Path to config file
+  -f, --force          Skip confirmation prompts
+  -d, --dry-run        Preview changes without executing
+  -v, --verbose        Show detailed output
+
+EXAMPLES
+  # Deploy to production
+  mycli deploy production
+
+  # Preview staging deployment
+  mycli deploy staging --dry-run
+
+  # Use custom config
+  mycli deploy --config ./custom.yml
+
+Learn more: https://docs.mycli.dev/deploy
+```