# @atlashub/smartstack-cli

[![npm version](https://img.shields.io/npm/v/@atlashub/smartstack-cli.svg)](https://www.npmjs.com/package/@atlashub/smartstack-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**SmartStack** transforms Claude Code into an enterprise-grade development platform. Stop writing boilerplate - start shipping features.

> **SmartStack** is your AI-powered co-pilot for .NET development: automated GitFlow, intelligent migrations, business analysis workflows, and battle-tested methodologies - all integrated directly into Claude Code.

## Why SmartStack?

- **10x Faster Development** - Pre-built workflows eliminate repetitive tasks
- **Enterprise GitFlow** - Full branch management with EF Core migration safety
- **Business Analysis Built-in** - From requirements to implementation handoff
- **Zero Configuration** - Install once, use everywhere

**By [AtlasHub](https://www.atlashub.ch)** | [support@atlashub.ch](mailto:support@atlashub.ch)

## What's New in v1.5.2

- **Azure DevOps Support** - Full GitFlow integration with Azure DevOps PRs and pipelines
- **npm Auto-Publish** - Automated publishing via Azure Pipelines (@next and @latest tags)
- **Ralph Loop Integration** - Fully automated BA orchestration with Ralph Loop framework
- **Prompts System** - Expert prompt creation and optimization tools
- **Quick Search** - Lightning-fast codebase exploration

---

## Table of Contents

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Update](#update)
- [Project Creation](#project-creation)
- [CLI Commands](#cli-commands)
- [Claude Code Commands](#claude-code-commands)
- [VS Code Configuration](#vs-code-configuration)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

### 1. Git

**Download:** https://git-scm.com/downloads

Git is **required** for GitFlow workflow and version control.

```powershell
# Verify installation
git --version

# Configure your identity
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
```

#### Option A: GitHub

```powershell
# Generate SSH key
ssh-keygen -t ed25519 -C "your@email.com"

# Start SSH agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Test connection
ssh -T git@github.com
```

**Add key on GitHub:** https://github.com/settings/keys

#### Option B: Azure DevOps

```powershell
# Git Credential Manager (recommended - included with Git for Windows)
git config --global credential.helper manager

# Clone a repo - credentials will be prompted automatically
git clone https://dev.azure.com/YourOrg/YourProject/_git/YourRepo
```

> **Windows Users:** Git Credential Manager handles Azure DevOps authentication automatically. On first clone, a browser window opens for login.

### 2. Node.js (v18 or higher)

**Download:** https://nodejs.org/

```powershell
node --version   # Should display v18.x.x or higher
npm --version    # Should display 9.x.x or higher
```

### 3. .NET SDK (v10.0 or higher)

**Download:** https://dotnet.microsoft.com/download

```powershell
dotnet --version   # Should display 10.x.x or higher
```

### 4. Visual Studio Code + Claude Code

**Download VS Code:** https://code.visualstudio.com/

Install Claude Code extension:
```powershell
code --install-extension anthropic.claude-code
```

Or manually: Open VS Code → Extensions (`Ctrl+Shift+X`) → Search "Claude Code" → Install

### 5. MCP Servers (Required)

MCP servers are **required** for SmartStack advanced features.

#### Step A: Download MCP packages

```powershell
# SmartStack MCP - Convention validation, scaffolding, API docs
npm install -g @atlashub/smartstack-mcp

# Context7 MCP - Library documentation, code examples
npm install -g @upstash/context7-mcp
```

#### Step B: Register in Claude Code

```powershell
# Register SmartStack MCP
claude mcp add smartstack -- npx @atlashub/smartstack-mcp

# Register Context7 MCP
claude mcp add context7 -- npx @upstash/context7-mcp

# Verify installation
claude mcp list
```

> **Expected result:** `claude mcp list` should show **smartstack** and **context7** in the active servers list.

---

## Installation

### Step 1: Install the npm package

```powershell
npm install -g @atlashub/smartstack-cli
```

### Step 2: Install commands into Claude Code

```powershell
smartstack install
```

Or with the short alias:
```powershell
ss install
```

### Step 3: Verify installation

```powershell
# Check installation status
smartstack status --verbose

# Run full diagnostic
smartstack doctor

# Verify MCP servers
smartstack check-mcp
```

### Local Installation (project only)

If you prefer a project-scoped installation:

```powershell
cd C:\path\to\your\project
smartstack install --local
```

---

## Update

### Update SmartStack CLI

```powershell
# Automatic update (package + commands)
smartstack update
```

### Manual Update

```powershell
# 1. Update npm package
npm update -g @atlashub/smartstack-cli

# 2. Reinstall commands
smartstack install --force
```

### Check for available updates

```powershell
npm outdated -g @atlashub/smartstack-cli
```

---

## Project Creation

### Method 1: `smartstack init` command (Recommended)

The `smartstack init` command creates a complete SmartStack project with an interactive wizard.

#### Interactive creation

```powershell
smartstack init MyProject
```

The wizard will ask for:
1. **Project type**: Full Stack, Backend Only, or Frontend Only
2. **Database**: SQL Server, PostgreSQL, or SQLite
3. **Modules**: Auth, Navigation, AI, Notifications

#### Quick creation (default values)

```powershell
smartstack init MyProject -y
```

#### Available options

| Option | Description |
|--------|-------------|
| `--full-stack` | Backend .NET + Frontend React (default) |
| `--backend` | Backend .NET only |
| `--frontend` | Frontend React only |
| `--db <type>` | Database: `sqlserver`, `postgresql`, `sqlite` |
| `--dry-run` | Simulation without creating files |
| `--skip-mcp-check` | Skip MCP servers verification |
| `-y, --yes` | Use default values |

#### Examples

```powershell
# Full-stack project with SQL Server (default)
smartstack init MyApp

# Backend only with PostgreSQL
smartstack init MyApi --backend --db postgresql

# Frontend only
smartstack init MyFrontend --frontend

# Simulation (see what would be created)
smartstack init MyProject --dry-run
```

#### Created structure

```
MyProject/
├── src/
│   ├── MyProject.Domain/           # Entities and interfaces
│   ├── MyProject.Application/      # Services and DTOs
│   ├── MyProject.Infrastructure/   # EF Core, repositories
│   └── MyProject.Api/              # Controllers and configuration
├── web/
│   └── myproject-web/              # Frontend React + Vite
├── tests/
├── MyProject.sln
├── Directory.Build.props
├── .gitignore
└── README.md
```

#### After creation

```powershell
cd MyProject

# 1. Configure connection string in appsettings.json

# 2. Create initial migration
dotnet ef migrations add InitialCreate -p src/MyProject.Infrastructure -s src/MyProject.Api

# 3. Apply migration
dotnet ef database update -p src/MyProject.Infrastructure -s src/MyProject.Api

# 4. Run backend
dotnet run --project src/MyProject.Api

# 5. Run frontend (another terminal)
cd web/myproject-web
npm run dev
```

### Method 2: Initialize existing project with GitFlow

If you already have a project and want to add GitFlow:

```powershell
cd C:\Projects\MyExistingProject
code .
```

In VS Code with Claude Code active:
```
/gitflow:1-init
```

---

## CLI Commands

All commands support the short alias `ss` (e.g., `ss install`, `ss status`).

### install

Install SmartStack commands, agents, and hooks.

```powershell
smartstack install [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--force` | `-f` | Overwrite existing files |
| `--global` | `-g` | Install to ~/.claude (default) |
| `--local` | `-l` | Install to ./.claude (project) |
| `--commands-only` | | Install only commands |
| `--agents-only` | | Install only agents |
| `--hooks-only` | | Install only hooks |
| `--no-config` | | Skip config file creation |
| `--no-plugins` | | Skip Claude Code plugin installation |

### uninstall

Remove SmartStack commands, agents, and hooks.

```powershell
smartstack uninstall [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--global` | `-g` | Uninstall from ~/.claude (default) |
| `--local` | `-l` | Uninstall from ./.claude |
| `--commands-only` | | Remove only commands |
| `--agents-only` | | Remove only agents |
| `--hooks-only` | | Remove only hooks |
| `--keep-config` | | Keep configuration file |
| `--yes` | `-y` | Skip confirmation prompt |

### status

Show installation status.

```powershell
smartstack status [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--global` | `-g` | Check ~/.claude (default) |
| `--local` | `-l` | Check ./.claude |
| `--verbose` | `-v` | Show detailed command list |

### update

Update commands to the latest version.

```powershell
smartstack update [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--global` | `-g` | Update ~/.claude (default) |
| `--local` | `-l` | Update ./.claude |

### init

Initialize a new SmartStack project.

```powershell
smartstack init <name> [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--full-stack` | | Backend + Frontend (default) |
| `--backend` | | Backend .NET only |
| `--frontend` | | Frontend React only |
| `--db <type>` | | Database: sqlserver, postgresql, sqlite |
| `--dry-run` | | Show what would be created |
| `--yes` | `-y` | Skip prompts, use defaults |
| `--skip-mcp-check` | | Skip MCP servers check |

### docs

Open SmartStack documentation in browser.

```powershell
smartstack docs [page] [options]
```

| Option | Alias | Description |
|--------|-------|-------------|
| `--list` | `-l` | List available documentation pages |

**Available pages:**
- `index` - Home page
- `installation` - Installation guide
- `commands` - Commands reference
- `agents` - Agents documentation
- `apex` - APEX methodology
- `business-analyse` - Business Analysis workflow
- `gitflow` - GitFlow workflow
- `efcore` - EF Core migrations
- `hooks` - Hooks configuration
- `test-web` - Web testing

**Examples:**
```powershell
smartstack docs                    # Open home page
smartstack docs gitflow            # Open GitFlow documentation
smartstack docs --list             # List all available pages
```

### license

Manage SmartStack CLI license.

```powershell
smartstack license <command> [options]
```

| Command | Description |
|---------|-------------|
| `activate <key>` | Activate a license key |
| `status` | Show current license status |
| `deactivate` | Remove the current license |
| `verify <key>` | Verify a license key without activating |

**Examples:**
```powershell
smartstack license activate ABC123-DEF456    # Activate license
smartstack license status                     # Check license status
smartstack license deactivate                 # Remove license
smartstack license verify ABC123-DEF456       # Verify without activating
```

---

## Claude Code Commands

### GitFlow Workflow

| Command | Description |
|---------|-------------|
| `/gitflow` | Full GitFlow workflow |
| `/gitflow:1-init` | Initialize GitFlow structure |
| `/gitflow:2-status` | Show repository status |
| `/gitflow:3-commit` | Smart commit with validation |
| `/gitflow:4-plan` | Create integration plan |
| `/gitflow:5-exec` | Execute integration plan |
| `/gitflow:6-abort` | Rollback operations |
| `/gitflow:10-start` | Start feature/release/hotfix |
| `/gitflow:11-finish` | Finish and tag |
| `/gitflow:12-cleanup` | Cleanup worktrees |
| `/gitflow:13-sync` | Sync with remote |
| `/gitflow:14-rebase` | Rebase on develop |
| `/gitflow:7-pull-request` | Create a Pull Request |
| `/gitflow:8-review` | Review a PR |
| `/gitflow:9-merge` | Merge a PR |

### Development Methodologies

| Command | Description |
|---------|-------------|
| `/apex` | APEX methodology (Analyze-Plan-Execute-eXamine) |
| `/epct` | Explore-Plan-Code-Test methodology |
| `/oneshot` | Ultra-fast implementation |
| `/debug` | Systematic debugging |
| `/explore` | Deep codebase exploration |
| `/explain` | Code explanation with diagrams |
| `/review` | Quick code review |
| `/implement` | Implementation from BA handoff |

### Business Analysis

| Command | Description |
|---------|-------------|
| `/business-analyse` | Full BA workflow with orchestration |
| `/business-analyse:1-init` | Initialize BA structure |
| `/business-analyse:2-discover` | Requirements elicitation |
| `/business-analyse:3-analyse` | Business analysis (BRD) |
| `/business-analyse:4-specify` | Functional specification (FRD) |
| `/business-analyse:5-validate` | User validation gate |
| `/business-analyse:6-handoff` | Implementation brief |
| `/business-analyse:7-doc-html` | Auto-generated HTML documentation |
| `/business-analyse:bug` | Bug resolution documentation |
| `/business-analyse:change-request` | Change request during development |

### EF Core Migrations

| Command | Description |
|---------|-------------|
| `/efcore` | EF Core orchestrator |
| `/efcore:migration` | Create/recreate migration |
| `/efcore:db-status` | Show migration status |
| `/efcore:db-deploy` | Apply migrations |
| `/efcore:db-seed` | Seed database |
| `/efcore:db-reset` | Reset database |
| `/efcore:scan` | Scan migrations across branches |
| `/efcore:conflicts` | Detect conflicts |
| `/efcore:rebase-snapshot` | Rebase ModelSnapshot |
| `/efcore:squash` | Squash multiple migrations |

### Prompts & Tools

| Command | Description |
|---------|-------------|
| `/prompts:create` | Expert prompt creation |
| `/prompts:agent` | Agent prompt optimization |
| `/prompts:command` | Command prompt patterns |
| `/prompts:claude-memory` | CLAUDE.md file management |

### Ralph Loop

| Command | Description |
|---------|-------------|
| `/ralph-loop` | Start autonomous Ralph Loop session |
| `/ralph-loop:cancel-ralph` | Cancel active Ralph Loop |
| `/ralph-loop:help` | Ralph Loop documentation |

### Quick Search

| Command | Description |
|---------|-------------|
| `/quick-search` | Lightning-fast codebase search |

---

## VS Code Configuration

### Recommended settings

Add to `.vscode/settings.json`:

```json
{
  "claude-code.enableSmartStack": true,
  "files.associations": {
    "*.md": "markdown"
  },
  "editor.formatOnSave": true
}
```

### Useful keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+P` | Command palette |
| `Ctrl+Shift+C` | Open Claude Code |
| `Ctrl+ù` | Integrated terminal |

---

## Troubleshooting

### "smartstack" is not recognized

**Cause:** npm global is not in PATH.

**Solution:**
```powershell
# Find npm global path
npm config get prefix

# Add to PATH (replace with your path)
$env:Path += ";C:\Users\YourName\AppData\Roaming\npm"
```

### Permission error

**Solution:** Run PowerShell as administrator, then:
```powershell
npm install -g @atlashub/smartstack-cli
```

### Commands don't appear in Claude Code

```powershell
# Reinstall with force
smartstack install --force

# Check status
smartstack status --verbose
```

### "MCP servers missing" error during `smartstack init`

**Solution:** Install required MCP servers:
```powershell
# 1. Download packages
npm install -g @atlashub/smartstack-mcp
npm install -g @upstash/context7-mcp

# 2. Register in Claude Code
claude mcp add smartstack -- npx @atlashub/smartstack-mcp
claude mcp add context7 -- npx @upstash/context7-mcp
```

Or skip verification:
```powershell
smartstack init MyProject --skip-mcp-check
```

### Complete reinstallation

```powershell
# Uninstall
smartstack uninstall
npm uninstall -g @atlashub/smartstack-cli

# Reinstall
npm install -g @atlashub/smartstack-cli
smartstack install
```

---

## Resources

- [Official Website](https://smartstack.app)
- [SmartStack Documentation](https://docs.smartstack.app)
- [GitFlow Documentation](.documentation/gitflow.html)
- [Business Analysis Documentation](.documentation/business-analyse.html)

---

## About AtlasHub

**[AtlasHub](https://www.atlashub.ch)** builds intelligent tools for modern development teams. SmartStack is our flagship CLI toolkit, designed to accelerate .NET and full-stack development with AI-powered automation.

**Need help?** Contact us at [support@atlashub.ch](mailto:support@atlashub.ch)

## Development

### Publishing

> **INTERDICTION DE PUBLIER MANUELLEMENT SUR NPM**
>
> La publication sur npm est **automatique** via Azure Pipelines.
> Ne jamais exécuter `npm publish` manuellement.
>
> **Workflow:**
> 1. Créer une release avec `/gitflow:10-start release`
> 2. Finaliser avec `/gitflow:11-finish`
> 3. Le tag déclenche automatiquement le pipeline de publication

## License

MIT - Free for personal and commercial use.
