zhongwei/gh-slamb2k-mad-skills-dev-flow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:58:05 +08:00
commit 36a6fff8d8
20 changed files with 4237 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
skills/start-right/references/project-types.md Normal file
View File

@@ -0,0 +1,220 @@
# Project Types Reference
This document provides detailed information about different project types and their specific requirements for validation, builds, and releases.
## Node.js / JavaScript Projects
**Detection**: `package.json` file present
**Typical validation checks**:
- Format: Prettier (`npm run format:check`)
- Lint: ESLint (`npm run lint`)
- Test: Jest/Vitest (`npm test`)
- Build: TypeScript/bundler (`npm run build`)
**Release strategies**:
- **npm package**: Publish to npm registry
- **Web app**: Deploy to Vercel, Netlify, or GitHub Pages
- **CLI tool**: Publish to npm with binary support
**Required dependencies**:
```json
{
"devDependencies": {
"prettier": "^3.0.0",
"eslint": "^8.0.0",
"jest": "^29.0.0" // or vitest
}
}
```
## TypeScript Projects
**Detection**: `tsconfig.json` or TypeScript in dependencies
**Typical validation checks**:
- Format: Prettier
- Lint: ESLint with TypeScript plugin
- Type check: `tsc --noEmit`
- Test: Jest/Vitest with ts-jest
- Build: TypeScript compiler
**Release strategies**: Same as Node.js
**Required dependencies**:
```json
{
"devDependencies": {
"typescript": "^5.0.0",
"@typescript-eslint/parser": "^6.0.0",
"@typescript-eslint/eslint-plugin": "^6.0.0",
"ts-jest": "^29.0.0"
}
}
```
## React Projects
**Detection**: React in `package.json` dependencies
**Typical validation checks**:
- Format: Prettier
- Lint: ESLint with React plugin
- Type check: TypeScript (if applicable)
- Test: Jest + React Testing Library
- Build: Vite/Webpack/Next.js
**Release strategies**:
- **Single-page app**: GitHub Pages, Vercel, Netlify
- **Next.js app**: Vercel (recommended), or Docker container
- **Component library**: npm package
**Additional considerations**:
- May need environment variable management
- Build optimization (bundle size, tree shaking)
- Static asset handling
## Rust Projects
**Detection**: `Cargo.toml` file present
**Typical validation checks**:
- Format: `cargo fmt --check`
- Lint: `cargo clippy -- -D warnings`
- Test: `cargo test`
- Build: `cargo build --release`
**Release strategies**:
- **Binary**: Cross-compile for multiple platforms, attach to GitHub Release
- **Library (crate)**: Publish to crates.io
- **Web Assembly**: Build to WASM for web deployment
**CI considerations**:
- Cache `~/.cargo` and `target/` directories
- Consider cross-compilation matrix for multiple platforms
- Separate debug/release builds
## Python Projects
**Detection**: `.py` files, `requirements.txt`, or `pyproject.toml`
**Typical validation checks**:
- Format: Black (`black --check .`)
- Lint: Flake8 (`flake8 .`)
- Type check: MyPy (`mypy .`)
- Test: Pytest (`pytest`)
**Release strategies**:
- **Package**: Publish to PyPI
- **CLI tool**: PyPI with entry points or standalone binary (PyInstaller)
- **Web service**: Docker container or Platform-as-a-Service
**Required tools**:
```txt
black
flake8
mypy
pytest
build # for packaging
```
## Go Projects
**Detection**: `go.mod` file present
**Typical validation checks**:
- Format: `go fmt` / `gofmt -s`
- Lint: `golangci-lint run`
- Test: `go test ./...`
- Build: `go build`
**Release strategies**:
- **Binary**: Cross-compile with GOOS/GOARCH, attach to GitHub Release
- **Library**: Tag version in git (Go modules)
- **Docker**: Multi-stage build for small images
**CI considerations**:
- Use Go module caching
- Cross-compilation for multiple platforms is straightforward
- Consider using GoReleaser for automated releases
## Docker Projects
**Detection**: `Dockerfile` present
**Typical validation checks**:
- Dockerfile lint: `hadolint Dockerfile`
- Build: `docker build .`
- Security scan: Trivy or similar
**Release strategies**:
- **Container image**: GitHub Container Registry (ghcr.io)
- **Docker Hub**: If public registry preferred
- **Multiple registries**: Push to multiple registries for redundancy
**Best practices**:
- Multi-stage builds for smaller images
- Use specific base image tags (not `latest`)
- Run as non-root user
- Regular security scanning
## Claude Code Skills
**Detection**: `.skill` extension or skill structure
**Typical validation checks**:
- Skill validation: Custom validator script
- Structure check: Verify SKILL.md frontmatter and structure
- Test: Use skill in Claude Code environment
**Release strategies**:
- **GitHub Release**: Attach packaged .skill file
- No deployment needed - users download and install manually
**Additional files**:
- SKILL.md (required)
- Optional: scripts/, references/, assets/ directories
- Package using skill packaging tool
## Web Applications (Generic)
**Typical validation checks**:
- Format checking
- Linting
- Unit tests
- Integration tests (optional on PR, required on main)
- Build verification
**Release strategies**:
- **Static site**: GitHub Pages, Vercel, Netlify
- **Server-rendered**: Platform-specific deployment (Vercel, Railway, Fly.io)
- **Containerized**: Deploy container to cloud platform
**Additional considerations**:
- Environment configuration management
- Asset optimization and CDN
- Database migrations (if applicable)
- Health check endpoints
## Best Practices Across All Types
### Validation Checks on PRs
- **Always run**: Format check, lint, unit tests, build
- **Optional**: Integration tests (if fast), type checking
- **Never run on PR**: Deployment, long-running tests
### Validation Checks on Main Branch
- **Always run**: All checks from PR + integration tests
- **Additionally**: Security scanning, coverage reports
- **After validation**: Versioning, tagging, release
### Versioning Strategy
- **Semantic versioning**: MAJOR.MINOR.PATCH
- **Auto-increment**: Use GitHub Actions to bump version
- **Tag format**: `v1.2.3` format recommended
- **Changelog**: Auto-generate from commit messages or PRs
### Release Notes
- Use GitHub's auto-generated release notes
- Customize with categories (features, fixes, breaking changes)
- Include links to related PRs and issues

351
skills/start-right/references/release-strategies.md Normal file
View File

@@ -0,0 +1,351 @@
# Release Strategies Reference
This document provides detailed guidance on different release strategies and deployment targets.
## npm Package Release
**Best for**: JavaScript/TypeScript libraries, CLI tools, frameworks
**Prerequisites**:
- npm account and NPM_TOKEN secret configured
- `package.json` with correct metadata (name, version, main, types)
- Build output in publishable state
**Workflow steps**:
1. Build the package
2. Run `npm publish`
3. Create GitHub Release with version tag
4. Include link to npm package in release notes
**Configuration**:
```json
{
"name": "@username/package-name",
"version": "1.0.0",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"files": ["dist"],
"scripts": {
"build": "tsc",
"prepublishOnly": "npm run build"
}
}
```
**GitHub Release notes example**:
```
📦 Published to npm: https://www.npmjs.com/package/@username/package-name
Install with:
npm install @username/package-name
```
## GitHub Pages Deployment
**Best for**: Static websites, documentation sites, SPAs
**Prerequisites**:
- GitHub Pages enabled in repository settings
- Build outputs static files to a directory (usually `dist/` or `build/`)
**Workflow steps**:
1. Build the static site
2. Deploy to `gh-pages` branch using `peaceiris/actions-gh-pages`
3. Create GitHub Release with link to live site
**Configuration considerations**:
- Set correct `base` path for SPAs (e.g., Vite: `base: '/repo-name/'`)
- Configure 404.html for SPA routing
- Custom domain setup (optional)
**GitHub Release notes example**:
```
🌐 Deployed to: https://username.github.io/repo-name
Changes in this release:
[auto-generated release notes]
```
## Vercel Deployment
**Best for**: Next.js apps, React apps, modern web frameworks
**Prerequisites**:
- Vercel account connected to GitHub
- Vercel project configured (can be done via CLI or UI)
**Workflow approaches**:
### Option 1: Automatic (Recommended)
- Let Vercel handle deployment via their GitHub integration
- GitHub Actions only handles validation
- Every push to main triggers Vercel deployment automatically
### Option 2: Manual via GitHub Actions
- Use Vercel CLI in GitHub Actions
- Requires VERCEL_TOKEN secret
- More control but more complex
**GitHub Release notes example**:
```
🚀 Deployed to Vercel: https://project-name.vercel.app
Production URL: https://your-domain.com (if custom domain)
```
## Docker Container Release
**Best for**: Microservices, backend applications, full-stack apps
**Prerequisites**:
- Dockerfile in repository
- Multi-stage builds for optimization (recommended)
**Release targets**:
- **GitHub Container Registry** (ghcr.io) - Recommended, free with GitHub
- **Docker Hub** - Public registry, widely used
- **AWS ECR**, **Google GCR**, **Azure ACR** - Cloud-specific registries
**Workflow steps**:
1. Build Docker image with version tag
2. Push to container registry
3. Also tag as `latest`
4. Create GitHub Release with pull command
**Best practices**:
- Use multi-stage builds to minimize image size
- Run containers as non-root user
- Include health check in Dockerfile
- Version images with semantic versioning
**GitHub Release notes example**:
```
🐳 Docker image: `ghcr.io/username/repo-name:v1.2.3`
Pull and run:
docker pull ghcr.io/username/repo-name:v1.2.3
docker run -p 8080:8080 ghcr.io/username/repo-name:v1.2.3
```
## Binary Artifacts Release
**Best for**: CLI tools, desktop apps, native applications
**Platforms to support**:
- Linux (x86_64, arm64)
- macOS (x86_64, arm64/Apple Silicon)
- Windows (x86_64)
**Workflow approaches**:
### Option 1: GitHub Actions matrix build
Build on multiple runners (ubuntu, macos, windows) and upload artifacts
### Option 2: Cross-compilation
Compile for multiple targets from single runner (works for Go, Rust)
### Option 3: GoReleaser / cargo-dist
Use specialized tools for automated multi-platform releases
**GitHub Release notes example**:
```
📥 Download the binary for your platform:
- Linux x86_64: [app-linux-amd64](link)
- Linux ARM64: [app-linux-arm64](link)
- macOS x86_64: [app-darwin-amd64](link)
- macOS ARM64: [app-darwin-arm64](link)
- Windows x86_64: [app-windows-amd64.exe](link)
Quick install:
curl -L https://github.com/user/repo/releases/download/v1.2.3/app-linux-amd64 -o app
chmod +x app
./app
```
## Python Package (PyPI) Release
**Best for**: Python libraries, CLI tools, frameworks
**Prerequisites**:
- PyPI account and API token
- `pyproject.toml` or `setup.py` with metadata
- Build tool (build, setuptools, poetry)
**Workflow steps**:
1. Build distribution packages (wheel + sdist)
2. Upload to PyPI using twine
3. Create GitHub Release with PyPI link
**Configuration**:
```toml
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my-package"
version = "1.0.0"
description = "Package description"
authors = [{name = "Your Name", email = "you@example.com"}]
```
**GitHub Release notes example**:
```
📦 Published to PyPI: https://pypi.org/project/my-package/
Install with:
pip install my-package
```
## Rust Crate (crates.io) Release
**Best for**: Rust libraries
**Prerequisites**:
- crates.io account
- CARGO_REGISTRY_TOKEN secret
- `Cargo.toml` with complete metadata
**Workflow steps**:
1. Run tests and validation
2. Publish to crates.io using `cargo publish`
3. Create GitHub Release
**GitHub Release notes example**:
```
📦 Published to crates.io: https://crates.io/crates/my-crate
Add to your Cargo.toml:
[dependencies]
my-crate = "1.0.0"
```
## Claude Code Skill Release
**Best for**: Claude Code skills and extensions
**Prerequisites**:
- Skill properly structured and validated
- Skill packaged as .skill file
**Workflow steps**:
1. Validate skill structure
2. Package skill into .skill file
3. Create GitHub Release with .skill file attached
4. No deployment needed
**GitHub Release notes example**:
```
🎯 Claude Code Skill Release
Download the skill file and install in Claude Code:
1. Download [skill-name.skill](link)
2. In Claude Code, run: /skills install /path/to/skill-name.skill
What's included:
- [Brief description of skill capabilities]
```
## Desktop App Distribution
**Best for**: Electron apps, Tauri apps
**Platforms**: Windows, macOS, Linux
**Workflow tools**:
- **Electron Builder**: Automated builds and updates
- **Tauri**: Rust-based alternative with smaller bundle sizes
**Distribution methods**:
- GitHub Releases with auto-updater
- Platform-specific stores (Microsoft Store, Mac App Store)
- Custom update server
## Platform-as-a-Service (PaaS) Deployment
**Platforms**: Railway, Fly.io, Render, Heroku (legacy)
**Common characteristics**:
- Git-based deployment
- Automatic container building
- Built-in databases and add-ons
- Easy environment variable management
**Workflow integration**:
Most PaaS platforms integrate directly with GitHub - just validation in GitHub Actions, deployment handled by platform
## Release Strategy Selection Guide
### Choose npm/PyPI/crates.io when:
- Building a library or package
- Want maximum distribution reach
- Package manager installation is preferred
### Choose GitHub Pages when:
- Pure static site
- Documentation site
- No server-side logic needed
- Want simple, free hosting
### Choose Vercel/Netlify when:
- Modern framework (Next.js, SvelteKit, etc.)
- Need serverless functions
- Want preview deployments for PRs
- Need automatic optimizations
### Choose Docker when:
- Microservices architecture
- Need consistent runtime environment
- Deploying to Kubernetes or container orchestration
- Complex dependencies
### Choose Binary release when:
- CLI tool
- Desktop application
- Want users to run without installing runtime
- Performance-critical application
### Choose PaaS when:
- Full-stack web application
- Need managed database
- Want simple deployment
- Solo developer or small team
## Multi-Release Strategy
Some projects benefit from multiple release targets:
**Example: CLI tool**
- npm package (for Node.js users)
- Standalone binary (for system installation)
- Docker image (for containerized environments)
**Example: Web framework**
- npm package (for developers)
- Documentation site on GitHub Pages
- Example deployed to Vercel
**Example: Library**
- Language package registry (npm, PyPI, etc.)
- GitHub Releases for changelogs
- Documentation site
## Versioning and Changelog Best Practices
**Semantic Versioning**:
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes
**Auto-versioning**:
Use commit messages or PR labels to determine version bump:
- `feat:` → MINOR bump
- `fix:` → PATCH bump
- `BREAKING CHANGE:` → MAJOR bump
**Changelog generation**:
- Auto-generate from commit messages (Conventional Commits)
- Auto-generate from PR titles
- Use GitHub's release notes generation
- Tools: semantic-release, conventional-changelog