@orchestrator-claude/definitions 3.5.0

package/skills/release/release.sh

@@ -0,0 +1,491 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# Release Script - Orchestrator v1.5.x
+# ============================================================================
+# Automates version bump and tag creation. CI/CD handles npm/Docker publish.
+#
+# Usage:
+#   ./scripts/release.sh patch    # 1.5.0 -> 1.5.1
+#   ./scripts/release.sh minor    # 1.5.0 -> 1.6.0
+#   ./scripts/release.sh major    # 1.5.0 -> 2.0.0
+#   ./scripts/release.sh 1.5.1    # Explicit version
+#
+# Files updated:
+#   - package.json (root)
+#   - packages/cli/package.json
+#   - packages/mcp-server/package.json
+#   - packages/sdk/package.json
+#   - packages/cli/src/index.ts (CLI_VERSION constant)
+#   - src/infrastructure/templates/base/package.json.hbs (template versions)
+#
+# ============================================================================
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Global variables
+FORCE=false
+DRY_RUN=false
+
+# Parse arguments
+VERSION_ARG=""
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -y|--yes|--force)
+      FORCE=true
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    -h|--help)
+      echo "Usage: $0 [options] <version>"
+      echo ""
+      echo "Version can be:"
+      echo "  patch         Increment patch version (1.4.1 -> 1.4.2)"
+      echo "  minor         Increment minor version (1.4.1 -> 1.5.0)"
+      echo "  major         Increment major version (1.4.1 -> 2.0.0)"
+      echo "  x.y.z         Explicit version number"
+      echo ""
+      echo "Options:"
+      echo "  -y, --yes, --force  Skip confirmation prompts"
+      echo "  --dry-run           Show what would be done without making changes"
+      echo "  -h, --help          Show this help message"
+      echo ""
+      echo "Examples:"
+      echo "  $0 patch            # Bump patch version"
+      echo "  $0 1.4.2            # Set explicit version"
+      echo "  $0 --dry-run patch  # Preview changes"
+      echo ""
+      echo "What this script does:"
+      echo "  1. Validates prerequisites and working tree"
+      echo "  2. Runs build to update dist/ with latest templates"
+      echo "  3. Bumps version in all package files"
+      echo "  4. Updates CLI_VERSION constant"
+      echo "  5. Commits version bump"
+      echo "  6. Creates and pushes git tag"
+      echo "  7. Tag push triggers CI/CD pipeline (npm + Docker publish)"
+      exit 0
+      ;;
+    *)
+      if [ -z "$VERSION_ARG" ]; then
+        VERSION_ARG="$1"
+      else
+        echo "Unknown option: $1"
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$VERSION_ARG" ]; then
+  echo -e "${RED}❌ Version argument required${NC}"
+  echo "Usage: $0 [patch|minor|major|x.y.z]"
+  echo "Run '$0 --help' for more information"
+  exit 1
+fi
+
+# ============================================================================
+# Utility Functions
+# ============================================================================
+
+log_info() {
+  echo -e "${BLUE}ℹ${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}✅${NC} $1"
+}
+
+log_warning() {
+  echo -e "${YELLOW}⚠️${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}❌${NC} $1"
+}
+
+# ============================================================================
+# Validation Functions
+# ============================================================================
+
+validate_prerequisites() {
+  echo "🔍 Validating prerequisites..."
+  local missing=()
+
+  # Check git
+  if ! command -v git &> /dev/null; then
+    missing+=("git")
+  fi
+
+  # Check node
+  if ! command -v node &> /dev/null; then
+    missing+=("node")
+  fi
+
+  # Check we're in the right directory
+  if [ ! -f "package.json" ] || [ ! -d "packages/cli" ]; then
+    log_error "Must be run from orchestrator root directory"
+    exit 1
+  fi
+
+  if [ ${#missing[@]} -ne 0 ]; then
+    log_error "Missing required tools: ${missing[*]}"
+    exit 1
+  fi
+
+  log_success "All prerequisites satisfied"
+}
+
+validate_working_tree() {
+  echo "🔍 Validating working tree..."
+
+  # Check if working tree is clean
+  if [ -n "$(git status --porcelain)" ]; then
+    log_error "Working tree is not clean"
+    echo "Please commit or stash your changes:"
+    git status --short
+    exit 1
+  fi
+
+  # Check if on main branch
+  local branch
+  branch=$(git rev-parse --abbrev-ref HEAD)
+
+  if [[ "$branch" != "main" ]]; then
+    log_warning "You are on branch '$branch', not main"
+    if [ "$FORCE" = true ]; then
+      echo "Continuing with --force flag..."
+    else
+      read -p "Continue anyway? (y/N): " -n 1 -r
+      echo
+      if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Aborted by user"
+        exit 1
+      fi
+    fi
+  fi
+
+  log_success "Working tree is clean"
+}
+
+validate_tag_not_exists() {
+  local tag=$1
+
+  if git rev-parse "$tag" &> /dev/null; then
+    log_error "Tag '$tag' already exists"
+    echo "Choose a different version or delete the existing tag"
+    exit 1
+  fi
+
+  log_success "Tag '$tag' is available"
+}
+
+# ============================================================================
+# Version Functions
+# ============================================================================
+
+get_current_version() {
+  node -p "require('./packages/cli/package.json').version"
+}
+
+calculate_new_version() {
+  local current=$1
+  local bump_type=$2
+
+  # Parse current version
+  local major minor patch
+  IFS='.' read -r major minor patch <<< "$current"
+
+  case $bump_type in
+    patch)
+      echo "${major}.${minor}.$((patch + 1))"
+      ;;
+    minor)
+      echo "${major}.$((minor + 1)).0"
+      ;;
+    major)
+      echo "$((major + 1)).0.0"
+      ;;
+    *)
+      # Assume it's an explicit version
+      if [[ "$bump_type" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "$bump_type"
+      else
+        log_error "Invalid version format: $bump_type"
+        echo "Use: patch, minor, major, or x.y.z format"
+        exit 1
+      fi
+      ;;
+  esac
+}
+
+# ============================================================================
+# Update Functions
+# ============================================================================
+
+update_package_version() {
+  local file=$1
+  local version=$2
+
+  if [ ! -f "$file" ]; then
+    log_warning "File not found: $file"
+    return
+  fi
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would update: $file"
+    return
+  fi
+
+  # Use node to update version (handles JSON properly)
+  node -e "
+    const fs = require('fs');
+    const pkg = JSON.parse(fs.readFileSync('$file', 'utf8'));
+    pkg.version = '$version';
+    fs.writeFileSync('$file', JSON.stringify(pkg, null, 2) + '\n');
+  "
+
+  log_info "Updated: $file"
+}
+
+update_cli_version_constant() {
+  local version=$1
+  local file="packages/cli/src/index.ts"
+
+  if [ ! -f "$file" ]; then
+    log_warning "File not found: $file"
+    return
+  fi
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would update CLI_VERSION in: $file"
+    return
+  fi
+
+  # Update CLI_VERSION constant
+  sed -i "s/export const CLI_VERSION = '[^']*'/export const CLI_VERSION = '${version}'/" "$file"
+
+  log_info "Updated CLI_VERSION in: $file"
+}
+
+update_template_version() {
+  local version=$1
+  local file="src/infrastructure/templates/base/package.json.hbs"
+
+  if [ ! -f "$file" ]; then
+    log_warning "Template file not found: $file"
+    return
+  fi
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would update template: $file"
+    return
+  fi
+
+  # Update @orchestrator-claude/cli and @orchestrator-claude/mcp-server versions
+  sed -i "s|\"@orchestrator-claude/cli\": \"\\^[0-9]*\\.[0-9]*\\.[0-9]*\"|\"@orchestrator-claude/cli\": \"^${version}\"|g" "$file"
+  sed -i "s|\"@orchestrator-claude/mcp-server\": \"\\^[0-9]*\\.[0-9]*\\.[0-9]*\"|\"@orchestrator-claude/mcp-server\": \"^${version}\"|g" "$file"
+
+  log_info "Updated template: $file"
+}
+
+update_all_versions() {
+  local version=$1
+
+  echo "📝 Updating versions to $version..."
+
+  # Update root package.json
+  update_package_version "package.json" "$version"
+
+  # Update CLI package
+  update_package_version "packages/cli/package.json" "$version"
+
+  # Update MCP server package
+  update_package_version "packages/mcp-server/package.json" "$version"
+
+  # Update SDK package
+  update_package_version "packages/sdk/package.json" "$version"
+
+  # Update CLI_VERSION constant
+  update_cli_version_constant "$version"
+
+  # Update templates
+  update_template_version "$version"
+
+  log_success "All versions updated to $version"
+}
+
+# ============================================================================
+# Build Functions
+# ============================================================================
+
+run_build() {
+  echo "🔨 Building project to update dist/..."
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would run: npm run build"
+    return
+  fi
+
+  # Run build to ensure dist/ has latest templates
+  if ! npm run build > /dev/null 2>&1; then
+    log_error "Build failed. Fix errors before releasing."
+    exit 1
+  fi
+
+  log_success "Build completed - dist/ updated with latest templates"
+}
+
+# ============================================================================
+# Git Functions
+# ============================================================================
+
+commit_version_bump() {
+  local version=$1
+  local tag="v${version}"
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would commit: chore: bump version to ${tag}"
+    return
+  fi
+
+  git add package.json \
+    packages/cli/package.json \
+    packages/mcp-server/package.json \
+    packages/sdk/package.json \
+    packages/cli/src/index.ts \
+    src/infrastructure/templates/base/package.json.hbs
+
+  git commit -m "chore: bump version to ${tag}
+
+Updates:
+- package.json (root)
+- packages/cli/package.json
+- packages/mcp-server/package.json
+- packages/sdk/package.json
+- packages/cli/src/index.ts (CLI_VERSION)
+- src/infrastructure/templates/base/package.json.hbs (templates)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+  log_success "Version bump committed"
+}
+
+create_and_push_tag() {
+  local version=$1
+  local tag="v${version}"
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would create tag: $tag"
+    echo "  [dry-run] Would push: main and $tag"
+    return
+  fi
+
+  # Create annotated tag
+  git tag -a "$tag" -m "Release $tag"
+  log_success "Tag created: $tag"
+
+  # Push commit and tag
+  echo "⬆️  Pushing to remote..."
+  git push origin main
+  git push origin "$tag"
+
+  log_success "Pushed main and tag $tag"
+}
+
+# ============================================================================
+# Main Flow
+# ============================================================================
+
+main() {
+  echo ""
+  echo -e "${BLUE}════════════════════════════════════════${NC}"
+  echo -e "${BLUE}  Orchestrator Release Script${NC}"
+  echo -e "${BLUE}════════════════════════════════════════${NC}"
+  echo ""
+
+  validate_prerequisites
+  validate_working_tree
+
+  # Get current and new versions
+  local current_version
+  current_version=$(get_current_version)
+
+  local new_version
+  new_version=$(calculate_new_version "$current_version" "$VERSION_ARG")
+
+  local tag="v${new_version}"
+
+  echo ""
+  echo -e "${BLUE}Release Plan:${NC}"
+  echo "  Current version: $current_version"
+  echo "  New version:     $new_version"
+  echo "  Git tag:         $tag"
+  echo ""
+
+  if [ "$DRY_RUN" = true ]; then
+    echo -e "${YELLOW}[DRY RUN MODE - No changes will be made]${NC}"
+    echo ""
+  fi
+
+  validate_tag_not_exists "$tag"
+
+  # Show what will be updated
+  echo ""
+  echo "Files to update:"
+  echo "  - package.json (root)"
+  echo "  - packages/cli/package.json"
+  echo "  - packages/mcp-server/package.json"
+  echo "  - packages/sdk/package.json"
+  echo "  - packages/cli/src/index.ts (CLI_VERSION)"
+  echo "  - src/infrastructure/templates/base/package.json.hbs (templates)"
+  echo ""
+  echo "Actions:"
+  echo "  1. Build project (update dist/ with latest templates)"
+  echo "  2. Update version in all files"
+  echo "  3. Commit version bump"
+  echo "  4. Create git tag $tag"
+  echo "  5. Push main + tag to origin"
+  echo "  6. CI/CD pipeline will publish npm + Docker"
+  echo ""
+
+  if [ "$FORCE" = false ] && [ "$DRY_RUN" = false ]; then
+    read -p "Continue with release? (y/N): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+      echo "Aborted by user"
+      exit 1
+    fi
+  fi
+
+  # Execute release steps
+  run_build
+  update_all_versions "$new_version"
+  commit_version_bump "$new_version"
+  create_and_push_tag "$new_version"
+
+  echo ""
+  echo -e "${GREEN}════════════════════════════════════════${NC}"
+  echo -e "${GREEN}  Release $tag initiated!${NC}"
+  echo -e "${GREEN}════════════════════════════════════════${NC}"
+  echo ""
+  echo "🚀 CI/CD pipeline will now:"
+  echo "   - Build and publish Docker image"
+  echo "   - Publish npm packages"
+  echo ""
+  echo "📍 Monitor pipeline at:"
+  echo "   https://github.com/orchestratorAII/orchestrator/actions"
+  echo ""
+}
+
+# Entry point
+main

package/skills/smoke-test/SKILL.md

@@ -0,0 +1,195 @@
+# Smoke Test Skill
+
+## Description
+
+Executes comprehensive API smoke tests against the Orchestrator API.
+Tests ALL endpoints from OpenAPI spec and generates detailed evidence.
+
+## When to Use
+
+- Before releases to validate API stability
+- After deployments to verify endpoints
+- During development to check for regressions
+- As part of CI/CD pipeline validation
+
+## Invocation
+
+```
+/smoke-test                 # Run all tiers
+/smoke-test --quick         # Tier 1-2 only (health + list)
+/smoke-test --full          # All tiers with verbose output
+/smoke-test --tier 3        # Specific tier only
+/smoke-test --format json   # JSON output only
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `--quick` | flag | false | Run only Tier 1-2 (fast validation) |
+| `--full` | flag | false | Run all tiers with verbose output |
+| `--tier N` | int | all | Filter to specific tier (1-4) |
+| `--format` | string | both | Output format: json, markdown, both |
+| `--verbose` | flag | false | Show detailed test output |
+| `--no-cleanup` | flag | false | Keep test data after completion |
+| `--url URL` | string | localhost:3001 | API base URL |
+
+## Test Tiers
+
+| Tier | Description | Tests |
+|------|-------------|-------|
+| 1 | Health & Connectivity | 5 tests |
+| 2 | List Endpoints | 14 tests |
+| 3 | CRUD Operations | 13 tests |
+| 3B | Workflow Sub-APIs | 12 tests* |
+| 3C | Invocations API | 2 tests |
+| 3D | Artifacts/Checkpoints/Patterns | 3 tests** |
+| 4 | Cleanup | 3 tests |
+
+**Total: 41 tests covering 76+ endpoints across 19 API groups**
+
+*Tier 3B tests require active workflow - skipped if workflow creation fails
+**Tier 3D tests require existing data - skipped if no artifacts/checkpoints/patterns exist
+
+## Output Artifacts
+
+After execution, the skill generates:
+
+```
+.orchestrator/artifacts/smoke-test/
+├── evidence-YYYY-MM-DD_HH-MM-SS.json   # Detailed JSON evidence
+└── report-YYYY-MM-DD_HH-MM-SS.md       # Human-readable report
+```
+
+### JSON Evidence Schema
+
+```json
+{
+  "meta": {
+    "version": "1.0.0",
+    "timestamp": "ISO8601",
+    "api_url": "string",
+    "duration_ms": number
+  },
+  "summary": {
+    "total": number,
+    "passed": number,
+    "failed": number,
+    "skipped": number,
+    "pass_rate": number
+  },
+  "results": [
+    {
+      "tier": number,
+      "category": "string",
+      "name": "string",
+      "method": "string",
+      "endpoint": "string",
+      "expected_codes": "string",
+      "actual_code": number,
+      "response_time_ms": number,
+      "passed": boolean,
+      "timestamp": "ISO8601",
+      "body": object
+    }
+  ]
+}
+```
+
+## Execution Flow
+
+```
+1. Parse arguments
+     │
+2. Execute Tier 1: Health
+     │
+3. Execute Tier 2: List all resources
+     │
+4. Execute Tier 3: Create/Update/Delete
+     │
+5. Execute Tier 4: Cleanup (if --no-cleanup not set)
+     │
+6. Generate reports (JSON + Markdown)
+     │
+7. Display summary
+```
+
+## Examples
+
+### Quick Validation (CI/CD)
+
+```bash
+/smoke-test --quick --format json
+```
+
+### Pre-Release Full Test
+
+```bash
+/smoke-test --full --verbose
+```
+
+### Debug Specific Tier
+
+```bash
+/smoke-test --tier 3 --verbose --no-cleanup
+```
+
+## Integration with Workflows
+
+This skill can be used as:
+
+1. **Post-IMPLEMENT hook** - Validate API after code changes
+2. **Pre-release validation** - Ensure stability before release
+3. **Regression detection** - Run after database migrations
+
+### Example Hook Configuration
+
+```json
+{
+  "slug": "post-implement-smoke-test",
+  "hookType": "post",
+  "triggerPhase": "implement",
+  "handlerType": "bash",
+  "handlerConfig": {
+    "command": "./scripts/smoke-test-api.sh --quick"
+  }
+}
+```
+
+## Prerequisites
+
+- Docker containers running (postgres, orchestrator-api)
+- `curl` and `jq` installed
+- API accessible at configured URL
+
+## Troubleshooting
+
+### API Not Responding
+
+```bash
+# Check container status
+docker compose ps orchestrator-api
+
+# Check API logs
+docker compose logs orchestrator-api --tail 50
+```
+
+### Tests Failing
+
+1. Check the generated report for details
+2. Run with `--verbose` for more output
+3. Run with `--no-cleanup` to inspect created data
+
+## Known Limitations
+
+### Agent CRUD Operations
+Agent Create/Read/Update/Delete may fail with 500 if the database schema migration
+for RFC-010 P2 has not been applied. The test accepts these failures gracefully.
+
+### Workflow Start
+Workflow creation may fail with 500 "Index not loaded" if the orchestrator service
+wasn't properly initialized. This is an environment issue, not a test issue.
+
+### Read-Only Resources
+Artifacts, Checkpoints, and Patterns tests are skipped if no resources exist.
+These are read-only endpoints that depend on prior workflow execution.