myaidev-method 0.2.5 → 0.2.6

package/USER_GUIDE.md

@@ -8,6 +8,9 @@ This guide covers everything you need to know about using, customizing, and exte
 
 - [Quick Start](#quick-start)
 - [Understanding the Structure](#understanding-the-structure)
+- [SPARC Development Workflow](#sparc-development-workflow)
+- [Git & CI/CD Workflows](#git--cicd-workflows)
+- [Multi-Platform Support](#multi-platform-support)
 - [Customizing Agents](#customizing-agents)
 - [Managing Commands](#managing-commands)
 - [WordPress Integration](#wordpress-integration)
@@ -19,12 +22,35 @@ This guide covers everything you need to know about using, customizing, and exte
 
 ## 🚀 Quick Start
 
-After installing with `npx myaidev-method init --claude`, you'll have a `.claude` folder in your project:
+After installing with `npx myaidev-method@latest init --claude`, you'll see the MyAIDev Method banner and SPARC methodology breakdown:
+
+```
+███╗   ███╗██╗   ██╗ █████╗ ██╗██████╗ ███████╗██╗   ██╗
+████╗ ████║╚██╗ ██╔╝██╔══██╗██║██╔══██╗██╔════╝██║   ██║
+...
+           ███╗   ███╗███████╗████████╗██╗  ██╗Օ   ██████╗  ██████╗
+...
+
+╔══════════════════════════════════════════════════════════════════════════╗
+║  SPARC Methodology - Systematic Software Development Framework         ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+  S │ 📋 Specification
+      Define requirements and system boundaries
+      → Clear goals, constraints, and success criteria
+
+  P │ 🔄 Pseudocode
+      Plan implementation approach
+      → Algorithm design and logic flow
+...
+```
+
+You'll have a `.claude` folder in your project:
 
 ```
 .claude/
-├── commands/           # Slash commands
-├── agents/            # AI agent definitions
+├── commands/           # Slash commands (22 total)
+├── agents/            # AI agent definitions (7 total)
 ├── mcp/              # MCP integrations
 └── CLAUDE.md         # Project configuration
 ```
@@ -32,9 +58,16 @@ After installing with `npx myaidev-method init --claude`, you'll have a `.claude
 ### Immediate Usage
 
 ```bash
+# SPARC Development Workflow
+/myai-sparc-workflow "Build user authentication system"
+
 # Create professional content
 /myai-content-writer "10 Best Remote Work Tips"
 
+# Git & CI/CD
+/myai-git-pr "Add authentication feature"
+/myai-deploy-staging
+
 # WordPress administration
 /myai-wordpress-admin health-check
 
@@ -46,17 +79,50 @@ After installing with `npx myaidev-method init --claude`, you'll have a `.claude
 
 ### Commands Directory (`.claude/commands/`)
 
-Contains slash commands that appear in your Claude Code interface:
-
-- `myai-content-writer.md` - Content creation command
-- `myai-wordpress-admin.md` - WordPress administration
+Contains 22 slash commands that appear in your Claude Code interface:
+
+**SPARC Development:**
+- `myai-sparc-workflow.md` - Complete 5-phase SPARC workflow
+- `myai-dev-architect.md` - Architecture design phase
+- `myai-dev-code.md` - Implementation phase
+- `myai-dev-test.md` - Testing phase
+- `myai-dev-review.md` - Code review phase
+- `myai-dev-docs.md` - Documentation phase
+
+**Git & CI/CD:**
+- `myai-git-pr.md` - Create and manage Pull Requests
+- `myai-git-release.md` - Semantic versioning and releases
+- `myai-git-sync.md` - Branch synchronization
+- `myai-git-hotfix.md` - Emergency hotfix procedures
+- `myai-deploy-dev.md` - Development environment deployment
+- `myai-deploy-staging.md` - Staging environment deployment
+- `myai-deploy-prod.md` - Production deployment (blue-green, canary, rolling)
+
+**Content & Publishing:**
+- `myai-content-writer.md` - Content creation
 - `myai-wordpress-publish.md` - WordPress publishing
+- `myai-wordpress-admin.md` - WordPress administration
+- `myai-payloadcms-publish.md` - PayloadCMS publishing
+- `myai-docusaurus-publish.md` - Docusaurus documentation
+- `myai-mintlify-publish.md` - Mintlify documentation
+- `myai-astro-publish.md` - Astro site publishing
+
+**Infrastructure:**
+- `myai-coolify-deploy.md` - Coolify deployment automation
 - `myai-configure.md` - Configuration management
 
 ### Agents Directory (`.claude/agents/`)
 
-Contains AI agent definitions with specialized prompts:
+Contains 7 AI agent definitions with specialized prompts:
 
+**Development Agents:**
+- `architect.md` - System architecture and design specialist
+- `coder.md` - Implementation and coding expert
+- `tester.md` - Testing and quality assurance specialist
+- `reviewer.md` - Code review and quality analysis
+- `documenter.md` - Technical documentation specialist
+
+**Content Agents:**
 - `content-writer.md` - Professional content creator
 - `wordpress-admin.md` - WordPress administrator
 
@@ -74,6 +140,321 @@ tools: Read, Write, Edit, WebSearch, WebFetch, Task
 # Agent prompt content goes here...
 ```
 
+## 🏗️ SPARC Development Workflow
+
+The SPARC methodology provides a systematic approach to software development with 5 phases:
+
+**S**pecification → **P**seudocode → **A**rchitecture → **R**efinement → **C**ompletion
+
+### Complete SPARC Workflow
+
+Run the entire 5-phase workflow:
+
+```bash
+/myai-sparc-workflow "Build user authentication with JWT and OAuth"
+```
+
+This executes all phases sequentially:
+1. **Specification** - Requirements analysis and system boundaries
+2. **Pseudocode** - Algorithm design and logic planning
+3. **Architecture** - System structure, APIs, and data models
+4. **Refinement** - Implementation with SOLID principles and testing
+5. **Completion** - Documentation and deployment preparation
+
+### Individual Phase Commands
+
+For more control, run phases individually:
+
+```bash
+# Phase 1: Architecture Design
+/myai-dev-architect "Design microservices architecture for e-commerce platform"
+
+# Phase 2: Implementation
+/myai-dev-code "Implement user authentication service"
+
+# Phase 3: Testing
+/myai-dev-test "Create comprehensive test suite with 80%+ coverage"
+
+# Phase 4: Code Review
+/myai-dev-review "Review authentication implementation for security"
+
+# Phase 5: Documentation
+/myai-dev-docs "Generate API documentation and user guides"
+```
+
+### SPARC Quality Standards
+
+All phases adhere to these standards:
+
+- **SOLID Principles**: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
+- **Clean Code**: DRY (Don't Repeat Yourself), KISS (Keep It Simple), YAGNI (You Aren't Gonna Need It)
+- **Security**: OWASP Top 10 compliance
+- **Testing**: 80%+ critical path coverage, 60%+ overall coverage
+- **Performance**: <200ms API responses, <50ms database queries
+
+### SPARC Output Structure
+
+All phases output to `.myaidev-method/sparc/` directory:
+
+```
+.myaidev-method/sparc/
+├── architecture.md          # Phase 1: System design
+├── pseudocode/             # Phase 2: Algorithm plans
+├── code-output/            # Phase 4: Implementation
+├── test-results/           # Phase 3: Test suites
+├── review-report.md        # Phase 4: Quality analysis
+└── documentation/          # Phase 5: API docs & guides
+```
+
+## 🔄 Git & CI/CD Workflows
+
+Complete Git operations and deployment automation commands:
+
+### Pull Request Workflow
+
+Create professional pull requests with GitHub CLI integration:
+
+```bash
+# Create PR from current branch
+/myai-git-pr "Add user authentication feature"
+
+# The command will:
+# - Analyze all commits since branch diverged
+# - Generate comprehensive PR description
+# - Create PR with gh CLI
+# - Include testing checklist and deployment notes
+```
+
+**PR Description Template includes:**
+- Summary of changes
+- Type of change (feature/fix/breaking)
+- Testing checklist
+- Code review checklist
+- Related issues
+- Screenshots (if applicable)
+- Deployment notes
+
+### Branch Synchronization
+
+Keep your branches in sync across the development workflow:
+
+```bash
+# Sync all branches
+/myai-git-sync
+
+# Features:
+# - Status overview of all branches
+# - Sync dev → staging → production
+# - Conflict resolution helper
+# - Branch cleanup (merged branches)
+```
+
+### Release Management
+
+Automated semantic versioning and changelog generation:
+
+```bash
+# Create new release
+/myai-git-release
+
+# Automatically:
+# - Determines version bump (major/minor/patch)
+# - Generates changelog from conventional commits
+# - Creates GitHub release
+# - Uploads assets with checksums
+# - Publishes to npm (if configured)
+```
+
+**Version Bump Detection:**
+- `BREAKING CHANGE` → major version (1.0.0 → 2.0.0)
+- `feat:` commits → minor version (1.0.0 → 1.1.0)
+- `fix:` commits → patch version (1.0.0 → 1.0.1)
+
+### Emergency Hotfix Procedures
+
+Fast-track critical bug fixes to production:
+
+```bash
+# Emergency hotfix workflow
+/myai-git-hotfix
+
+# Includes:
+# - Emergency assessment & incident tracking
+# - Multiple fix application methods
+# - Fast-track testing
+# - Emergency approval gate
+# - Post-mortem report generation
+```
+
+### Deployment Commands
+
+Deploy to different environments with appropriate safety levels:
+
+```bash
+# Development deployment (fast iteration)
+/myai-deploy-dev
+
+# Staging deployment (pre-production testing)
+/myai-deploy-staging
+
+# Production deployment (multiple strategies)
+/myai-deploy-prod
+```
+
+**Development Deployment:**
+- Fast deployment with hot-reload support
+- Docker, Docker Compose, or rsync methods
+- Auto-deploy via GitHub Actions
+
+**Staging Deployment:**
+- Pre-flight checks and tests
+- Coolify or Docker deployment
+- Health checks and smoke tests
+- Rollback procedures
+
+**Production Deployment:**
+- Strict approval gates and backup points
+- Multiple strategies:
+  - **Blue-Green**: Zero-downtime deployment
+  - **Canary**: Gradual rollout (10% → 50% → 100%)
+  - **Rolling**: Sequential instance updates
+- Comprehensive monitoring and rollback
+
+### Deployment Methods
+
+All deployment commands support:
+
+**Coolify API:**
+```bash
+# Configure Coolify credentials
+COOLIFY_URL=https://coolify.your-server.com
+COOLIFY_API_TOKEN=your_api_token
+COOLIFY_STAGING_APP_ID=your_app_id
+```
+
+**Docker:**
+```bash
+# Docker deployment
+DOCKER_REGISTRY=registry.your-domain.com
+STAGING_IMAGE_TAG=staging
+```
+
+**Docker Compose:**
+```bash
+# Deploy with compose
+ssh staging-server 'cd /opt/app && docker-compose up -d'
+```
+
+### CI/CD Notifications
+
+Deployment commands support notifications:
+
+```bash
+# Slack notifications
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK
+
+# Discord notifications
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/WEBHOOK
+```
+
+## 🌐 Multi-Platform Support
+
+MyAIDev Method supports three AI CLI platforms with feature parity:
+
+### Claude Code (Default)
+
+Uses `.claude/` directory structure:
+
+```bash
+# Initialize for Claude Code
+npx myaidev-method@latest init --claude
+
+# Structure
+.claude/
+├── commands/           # Markdown with YAML frontmatter
+│   └── myai-*.md      # Uses $ARGUMENTS placeholder
+├── agents/
+├── mcp/
+└── CLAUDE.md
+```
+
+### Gemini CLI
+
+Uses `.gemini/` directory with TOML format:
+
+```bash
+# Initialize for Gemini CLI
+npx myaidev-method@latest init --gemini
+
+# Structure
+.gemini/
+├── commands/           # TOML format
+│   └── myai-*.toml    # Uses {{args}} placeholder
+└── README.md
+```
+
+**Gemini Command Format:**
+```toml
+prompt = """
+You are a specialist in...
+
+Task: {{args}}
+
+## Workflow
+...
+"""
+```
+
+### OpenCode (Codex)
+
+Uses `.opencode/` directory with simple Markdown:
+
+```bash
+# Initialize for OpenCode
+npx myaidev-method@latest init --opencode
+
+# Structure
+.opencode/
+├── commands/           # Simple Markdown (no frontmatter)
+│   └── myai-*.md      # Uses $ARGUMENTS placeholder
+└── README.md
+```
+
+**OpenCode Command Format:**
+```markdown
+# Command Description
+
+You are a specialist in...
+
+Task: $ARGUMENTS
+
+## Workflow
+...
+```
+
+### Platform Feature Parity
+
+All 22 commands are available on all platforms:
+- ✅ Claude Code: 22 commands + 7 agents
+- ✅ Gemini CLI: 22 commands (TOML format)
+- ✅ OpenCode: 22 commands (simple Markdown)
+
+### Switching Platforms
+
+You can initialize for multiple platforms in the same project:
+
+```bash
+# Initialize all platforms
+npx myaidev-method@latest init --claude
+npx myaidev-method@latest init --gemini
+npx myaidev-method@latest init --opencode
+
+# Result: All three directories exist
+.claude/
+.gemini/
+.opencode/
+```
+
 ## 🎨 Customizing Agents
 
 ### Method 1: Direct File Editing