@atlashub/smartstack-cli 1.4.0 → 1.5.0

package/templates/commands/create/command.md

@@ -0,0 +1,166 @@
+---
+description: Create a SmartStack command extension project
+argument-hint: <name> [description]
+---
+
+# Create Command Extension
+
+Scaffold a complete SmartStack **command** extension project.
+
+## What is a Command?
+
+A command is a slash command that users invoke in Claude Code:
+- `/my-command <args>` - Executes the command with arguments
+- Defined in markdown with YAML frontmatter
+- Contains workflow, rules, and execution logic
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **name** (required): Command name in kebab-case
+- **description** (optional): What the command does
+
+## Project Structure
+
+```
+smartstack-{name}/
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── README.md
+├── .gitignore
+├── src/
+│   └── index.ts
+└── templates/
+    └── commands/
+        └── {name}.md          # Main command template
+```
+
+## Generated Command Template
+
+Create `templates/commands/{name}.md`:
+
+```markdown
+---
+description: {description}
+argument-hint: <task-description>
+---
+
+# {PascalCaseName}
+
+{description}
+
+## Workflow
+
+### 1. UNDERSTAND
+- Parse user arguments: `$ARGUMENTS`
+- Identify the task scope
+- Gather necessary context
+
+### 2. ANALYZE
+- Explore relevant codebase areas
+- Identify patterns and constraints
+- Document findings
+
+### 3. PLAN
+- Design the approach
+- Consider edge cases
+- Validate against requirements
+
+### 4. EXECUTE
+- Implement step by step
+- Follow existing patterns
+- Write clean code
+
+### 5. VERIFY
+- Test the implementation
+- Ensure no regressions
+- Validate completeness
+
+## Execution Rules
+
+1. **ULTRA THINK** before each phase
+2. Use parallel agents when beneficial
+3. Document all decisions
+4. **MINIMAL CHANGES**: Only what's needed
+5. Test before declaring complete
+
+## Agent Usage
+
+For exploration, launch agents:
+- `explore-codebase` - Find relevant files
+- `websearch` - Research solutions
+
+## Priority
+
+Understanding > Correctness > Speed
+
+---
+
+User: $ARGUMENTS
+```
+
+## Generated Files
+
+### package.json
+
+```json
+{
+  "name": "@smartstack/{name}",
+  "version": "1.0.0",
+  "description": "{description}",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "@atlashub/smartstack-cli": ">=1.0.0"
+  }
+}
+```
+
+### src/index.ts
+
+```typescript
+import * as path from 'path';
+import * as fs from 'fs';
+
+export function getTemplatesPath(): string {
+  return path.join(__dirname, '..', 'templates');
+}
+
+export async function install(targetDir: string): Promise<void> {
+  const src = path.join(getTemplatesPath(), 'commands');
+  const dest = path.join(targetDir, 'commands');
+  // Copy command templates
+}
+
+export const metadata = {
+  name: '{name}',
+  version: '1.0.0',
+  description: '{description}',
+  type: 'command'
+};
+```
+
+## Workflow
+
+1. Parse name and description from `$ARGUMENTS`
+2. Validate name is kebab-case
+3. Create project directory
+4. Generate all files using Write tool
+5. Display success message with next steps
+
+## Validation
+
+- Name must match: `^[a-z][a-z0-9-]*$`
+- Directory must not exist
+- Description should be meaningful
+
+---
+
+User: $ARGUMENTS

package/templates/commands/create/hook.md

@@ -0,0 +1,234 @@
+---
+description: Create a SmartStack hook extension project
+argument-hint: <name> [trigger] [description]
+---
+
+# Create Hook Extension
+
+Scaffold a complete SmartStack **hook** extension project.
+
+## What is a Hook?
+
+A hook is a validation/action trigger:
+- Runs automatically at specific points (pre-commit, pre-merge, etc.)
+- Can block operations if issues detected
+- Defined in markdown with detection patterns
+- Integrates with GitFlow workflow
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **name** (required): Hook name in kebab-case
+- **trigger** (optional): pre-commit | pre-merge | pre-push | post-commit
+- **description** (optional): What the hook validates
+
+## Project Structure
+
+```
+smartstack-{name}/
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── README.md
+├── .gitignore
+├── src/
+│   └── index.ts
+└── templates/
+    └── hooks/
+        └── {name}.md          # Hook template
+```
+
+## Generated Hook Template
+
+```markdown
+---
+description: {description}
+trigger: {trigger}
+blocking: true
+---
+
+# {PascalCaseName} Hook
+
+{description}
+
+## Purpose
+
+This hook validates [what it validates] before allowing [the action].
+
+## Trigger Points
+
+| Trigger | When | Blocking |
+|---------|------|----------|
+| pre-commit | Before git commit | Yes |
+| pre-merge | Before branch merge | Yes |
+| pre-push | Before git push | Yes |
+| post-commit | After git commit | No |
+
+Current trigger: **{trigger}**
+
+## Detection Patterns
+
+### BLOCKING Patterns
+
+These patterns will **prevent** the operation:
+
+| Pattern | File Types | Risk Level | Reason |
+|---------|-----------|------------|--------|
+| `PATTERN_ONE` | *.ts, *.js | Critical | Description |
+| `PATTERN_TWO` | *.sql | High | Description |
+| `PATTERN_THREE` | * | Medium | Description |
+
+### WARNING Patterns
+
+These patterns will **warn** but allow:
+
+| Pattern | File Types | Reason |
+|---------|-----------|--------|
+| `WARN_PATTERN` | *.ts | Description |
+
+## Detection Script
+
+```bash
+#!/bin/bash
+# {PascalCaseName} Hook
+# {description}
+
+set -e
+
+echo "🔍 Running {name} check..."
+
+# Configuration
+BLOCKING_PATTERNS=(
+  "PATTERN_ONE"
+  "PATTERN_TWO"
+)
+
+WARNING_PATTERNS=(
+  "WARN_PATTERN"
+)
+
+FILE_TYPES="*.ts *.js *.tsx *.jsx"
+
+FOUND_BLOCKING=0
+FOUND_WARNING=0
+
+# Check blocking patterns
+for pattern in "${BLOCKING_PATTERNS[@]}"; do
+  if grep -rn "$pattern" --include="$FILE_TYPES" . 2>/dev/null; then
+    echo "❌ BLOCKING: Found '$pattern'"
+    FOUND_BLOCKING=$((FOUND_BLOCKING + 1))
+  fi
+done
+
+# Check warning patterns
+for pattern in "${WARNING_PATTERNS[@]}"; do
+  if grep -rn "$pattern" --include="$FILE_TYPES" . 2>/dev/null; then
+    echo "⚠️  WARNING: Found '$pattern'"
+    FOUND_WARNING=$((FOUND_WARNING + 1))
+  fi
+done
+
+# Results
+if [ $FOUND_BLOCKING -gt 0 ]; then
+  echo ""
+  echo "╔═══════════════════════════════════════════╗"
+  echo "║  ❌ HOOK BLOCKED: $FOUND_BLOCKING issues found  ║"
+  echo "╚═══════════════════════════════════════════╝"
+  echo ""
+  echo "Fix the issues above or bypass with:"
+  echo "  SKIP_{NAME_UPPER}_HOOK=1 git commit -m 'message'"
+  exit 1
+fi
+
+if [ $FOUND_WARNING -gt 0 ]; then
+  echo ""
+  echo "⚠️  $FOUND_WARNING warnings found (non-blocking)"
+fi
+
+echo "✅ Hook PASSED"
+exit 0
+```
+
+## Integration
+
+### With GitFlow
+
+In `/gitflow:3-commit`, this hook runs automatically:
+
+1. User initiates commit
+2. Hook executes detection script
+3. If blocking patterns found → commit rejected
+4. User must fix or explicitly bypass
+
+### Manual Execution
+
+```bash
+# Run hook manually
+./.claude/hooks/{name}.sh
+
+# Check specific files
+./.claude/hooks/{name}.sh src/specific-file.ts
+```
+
+## Bypass (Emergency Only)
+
+```bash
+# Use with extreme caution!
+SKIP_{NAME_UPPER}_HOOK=1 git commit -m "message"
+
+# Or in environment
+export SKIP_{NAME_UPPER}_HOOK=1
+```
+
+**WARNING**: Bypassing should be documented and justified.
+
+## Logging
+
+All detections logged to:
+`~/.claude/gitflow/logs/{name}.json`
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "hook": "{name}",
+  "trigger": "{trigger}",
+  "result": "blocked|passed|warning",
+  "blocking_issues": [],
+  "warnings": [],
+  "branch": "feature/xxx",
+  "user": "username"
+}
+```
+
+## Customization
+
+Edit patterns in the hook file:
+- Add new blocking patterns
+- Adjust file type filters
+- Customize error messages
+
+## Priority
+
+Security > Correctness > Speed
+```
+
+## Trigger Options
+
+| Trigger | Use Case |
+|---------|----------|
+| `pre-commit` | Validate before local commit |
+| `pre-merge` | Validate before branch merge |
+| `pre-push` | Validate before pushing to remote |
+| `post-commit` | Log/notify after commit |
+
+## Workflow
+
+1. Parse arguments (name, trigger, description)
+2. Validate name format
+3. Create project directory
+4. Generate hook template with proper trigger
+5. Display success message
+
+---
+
+User: $ARGUMENTS

package/templates/commands/create/plugin.md

@@ -0,0 +1,329 @@
+---
+description: Create a complete SmartStack plugin with all extension types
+argument-hint: <name> [description]
+---
+
+# Create Plugin Extension
+
+Scaffold a complete SmartStack **plugin** with command, agent, skill, and hook.
+
+## What is a Plugin?
+
+A plugin is a full-featured extension package containing:
+- **Command**: Main entry point for users
+- **Agent**: Specialized execution unit
+- **Skill**: Multi-phase workflow
+- **Hook**: Validation trigger
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+- **name** (required): Plugin name in kebab-case
+- **description** (optional): What the plugin does
+
+## Project Structure
+
+```
+smartstack-{name}/
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── README.md
+├── .gitignore
+├── LICENSE
+├── src/
+│   └── index.ts
+├── templates/
+│   ├── commands/
+│   │   ├── {name}.md              # Main command
+│   │   └── {name}/
+│   │       ├── analyze.md         # Sub-command
+│   │       └── execute.md         # Sub-command
+│   ├── agents/
+│   │   └── {name}.md              # Plugin agent
+│   ├── skills/
+│   │   └── {name}/
+│   │       ├── SKILL.md           # Skill definition
+│   │       ├── 1-setup.md
+│   │       ├── 2-analyze.md
+│   │       ├── 3-execute.md
+│   │       └── templates.md
+│   └── hooks/
+│       └── {name}-check.md        # Plugin hook
+└── examples/
+    └── usage.md                   # Usage examples
+```
+
+## Generated Files
+
+### Main Command (templates/commands/{name}.md)
+
+```markdown
+---
+description: {description}
+argument-hint: <task> [options]
+---
+
+# {PascalCaseName}
+
+{description}
+
+## Available Sub-Commands
+
+| Command | Description |
+|---------|-------------|
+| `/{name}` | Run default workflow |
+| `/{name}:analyze` | Analysis only |
+| `/{name}:execute` | Execution only |
+
+## Quick Start
+
+```
+/{name} <your-task>
+```
+
+## Workflow
+
+### 1. ANALYZE
+Launch `{name}` agent for exploration.
+
+### 2. PLAN
+Design approach based on analysis.
+
+### 3. EXECUTE
+Implement using skill phases.
+
+### 4. VALIDATE
+Verify with `{name}-check` hook.
+
+## Priority
+
+Quality > Speed > Cost
+
+---
+
+User: $ARGUMENTS
+```
+
+### Plugin Agent (templates/agents/{name}.md)
+
+```markdown
+---
+name: {name}
+description: Agent for {name} operations
+color: cyan
+model: sonnet
+---
+
+# {PascalCaseName} Agent
+
+Specialized agent for {name} analysis and execution.
+
+## Capabilities
+
+1. **Discovery**: Find relevant files and patterns
+2. **Analysis**: Deep code analysis
+3. **Recommendations**: Actionable suggestions
+
+## Search Strategy
+
+1. Use `Glob` for file discovery
+2. Use `Grep` for pattern matching
+3. Use `Read` for detailed analysis
+
+## Output Format
+
+### Analysis Report
+
+#### Files Analyzed
+[List of relevant files]
+
+#### Findings
+[Detailed findings]
+
+#### Recommendations
+[Actionable recommendations]
+
+## Priority
+
+Accuracy > Completeness > Speed
+```
+
+### Plugin Skill (templates/skills/{name}/SKILL.md)
+
+```markdown
+---
+name: {name}
+description: Multi-phase workflow for {name}
+---
+
+# {PascalCaseName} Skill
+
+## Phases
+
+| Phase | Command | Model | Cost |
+|-------|---------|-------|------|
+| 1 | `/{name}:1-setup` | Haiku | ~$0.02 |
+| 2 | `/{name}:2-analyze` | Sonnet | ~$0.10 |
+| 3 | `/{name}:3-execute` | Opus | ~$0.30 |
+
+## Workflow
+
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│  SETUP   │ ──▶ │ ANALYZE  │ ──▶ │ EXECUTE  │
+└──────────┘     └──────────┘     └──────────┘
+```
+
+## Usage
+
+```
+/{name}            # Full workflow
+/{name}:1-setup    # Setup only
+```
+
+## Priority
+
+Quality > Cost > Speed
+```
+
+### Plugin Hook (templates/hooks/{name}-check.md)
+
+```markdown
+---
+description: Validation hook for {name}
+trigger: pre-commit
+blocking: true
+---
+
+# {PascalCaseName} Check Hook
+
+Validates {name} operations before commit.
+
+## Patterns
+
+### BLOCKING
+- `DANGEROUS_PATTERN` - Prevents commit
+
+### WARNING
+- `MILD_CONCERN` - Logs warning
+
+## Integration
+
+Runs automatically in `/gitflow:3-commit`.
+
+## Bypass
+
+```bash
+SKIP_{NAME_UPPER}_CHECK_HOOK=1 git commit
+```
+```
+
+### package.json
+
+```json
+{
+  "name": "@smartstack/{name}",
+  "version": "1.0.0",
+  "description": "{description}",
+  "author": "AtlasHub",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "@atlashub/smartstack-cli": ">=1.0.0"
+  },
+  "keywords": ["smartstack", "claude", "extension", "{name}"]
+}
+```
+
+### README.md
+
+```markdown
+# SmartStack {PascalCaseName} Plugin
+
+{description}
+
+## Installation
+
+```bash
+npm install @smartstack/{name}
+smartstack install --extension @smartstack/{name}
+```
+
+## Components
+
+| Type | Command | Description |
+|------|---------|-------------|
+| Command | `/{name}` | Main entry point |
+| Agent | `{name}` | Analysis agent |
+| Skill | `/{name}:*` | Multi-phase workflow |
+| Hook | `{name}-check` | Validation |
+
+## Usage
+
+```
+/{name} <your-task>
+```
+
+## License
+
+MIT
+```
+
+## Workflow
+
+1. Parse name and description from `$ARGUMENTS`
+2. Validate name format (kebab-case)
+3. Create complete directory structure
+4. Generate all component files:
+   - Command + sub-commands
+   - Agent
+   - Skill + phases
+   - Hook
+5. Generate package.json, README, etc.
+6. Display success message with component list
+
+## Validation
+
+Before creating:
+- Name must be kebab-case
+- Directory must not exist
+- All paths must be valid
+
+## Success Output
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║           SMARTSTACK PLUGIN CREATED                       ║
+╠═══════════════════════════════════════════════════════════╣
+║  Name:     smartstack-{name}                              ║
+║  Type:     Full Plugin                                    ║
+╠═══════════════════════════════════════════════════════════╣
+║  Components:                                              ║
+║  ✓ Command:  /{name}                                      ║
+║  ✓ Agent:    {name}                                       ║
+║  ✓ Skill:    /{name}:* (3 phases)                         ║
+║  ✓ Hook:     {name}-check                                 ║
+╠═══════════════════════════════════════════════════════════╣
+║  Next steps:                                              ║
+║  1. cd smartstack-{name}                                  ║
+║  2. npm install                                           ║
+║  3. Customize templates                                   ║
+║  4. npm run build                                         ║
+║  5. npm publish                                           ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+## Priority
+
+Completeness > Quality > Speed
+
+---
+
+User: $ARGUMENTS