@cloudkinetix/bmad-enhanced/ck-layer/docs/PRE-PUBLISH-CHECKLIST.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# Pre-Publish Checklist for BMAD Enhanced

This checklist MUST be completed before ANY publication to NPM. Given the critical nature of this project, we maintain a zero-tolerance policy for installation failures.

## 🚨 Critical Pre-Publish Steps

### 1. Code Quality Verification

- [ ] All changes reviewed and tested locally
- [ ] No console errors or warnings during development
- [ ] All TODO items addressed or documented
- [ ] Code follows established patterns and conventions

### 2. Dependency Verification

- [ ] Run `npm install` - must complete without errors
- [ ] Run `npm ls` - no missing or conflicting dependencies
- [ ] Verify chalk is properly imported in all CK layer files
- [ ] Check all require() statements resolve correctly

### 3. Local Testing Suite

```bash
# Run comprehensive local tests
npm run test:pre-publish

# All tests MUST pass before proceeding
```

- [ ] Cursor + JIRA installation test passed
- [ ] Trae + JIRA installation test passed
- [ ] Multiple expansion packs test passed
- [ ] Default installation test passed
- [ ] Full installation test passed
- [ ] Expansion-only installation test passed
- [ ] Status command works correctly
- [ ] List commands work correctly
- [ ] Backup functionality verified
- [ ] All IDE installations tested

### 4. Manual Verification Tests

```bash
# Test 1: Clean installation
rm -rf test-manual
node ck-layer/bin/bmad-enhanced.js install --ide cursor --expansion-packs ck-jira-integration --directory test-manual

# Verify:
- [ ] No errors during installation
- [ ] .cursor/rules/jira.mdc exists
- [ ] No "Cannot read properties of undefined" errors

# Test 2: Trae installation
rm -rf test-manual-trae
node ck-layer/bin/bmad-enhanced.js install --ide trae --expansion-packs ck-jira-integration --directory test-manual-trae

# Verify:
- [ ] .trae/rules/project_rules.md exists
- [ ] @jira agent is included
- [ ] No errors during installation

# Test 3: Full installation (most critical)
rm -rf test-manual-full
node ck-layer/bin/bmad-enhanced.js install --full --directory test-manual-full

# Verify:
- [ ] All expansion packs installed
- [ ] All IDEs configured
- [ ] No errors at any stage
```

### 5. Version Management

- [ ] Version number incremented appropriately
- [ ] package.json version matches intended release
- [ ] CHANGELOG updated (if applicable)
- [ ] README version badges will update automatically

### 6. Git Status

- [ ] All changes committed
- [ ] Working directory is clean
- [ ] Branch is up to date with origin
- [ ] No merge conflicts

### 7. NPM Readiness

- [ ] .env file contains valid NPM_TOKEN
- [ ] Currently logged in to NPM (verify with `npm whoami`)
- [ ] Target tag determined (beta or latest)

### 8. Documentation

- [ ] README accurately reflects all features
- [ ] Installation commands tested and working
- [ ] Known issues documented
- [ ] Breaking changes highlighted (if any)

## 🚀 Publishing Process

### Safe Publishing (Recommended)

```bash
# This runs all tests before publishing
npm run publish:safe
```

### Manual Publishing Steps

1. Run all pre-publish tests:

   ```bash
   npm run test:pre-publish
   ```

2. If all tests pass, publish beta:

   ```bash
   npm run publish beta
   ```

3. Test the published package:

   ```bash
   npx @cloudkinetix/bmad-enhanced@beta install --ide cursor --directory test-published
   ```

4. Only after beta validation, publish stable:
   ```bash
   npm run publish stable
   ```

## 🔴 Stop Conditions

DO NOT PUBLISH if any of these conditions exist:

1. **Any test failure** in the pre-publish suite
2. **Chalk errors** ("Cannot read properties of undefined")
3. **Installation errors** during manual testing
4. **Missing files** in the published package
5. **Dependency resolution issues**
6. **Git working directory not clean**
7. **Version conflicts or confusion**

## 📋 Post-Publish Verification

After publishing, ALWAYS:

1. Install the published package in a clean directory:

   ```bash
   npx @cloudkinetix/bmad-enhanced@[version] install --ide cursor --directory verify-published
   ```

2. Verify core functionality:
   - [ ] Installation completes without errors
   - [ ] IDE configurations created correctly
   - [ ] Expansion packs work as expected
   - [ ] No regression in features

3. Update GitHub:
   - [ ] Push all commits
   - [ ] Create release notes if stable version
   - [ ] Update any related documentation

## 🆘 Rollback Procedure

If issues are discovered post-publish:

1. Unpublish the broken version (if within 72 hours):

   ```bash
   npm unpublish @cloudkinetix/bmad-enhanced@[version]
   ```

2. Or publish a patch fix immediately:

   ```bash
   npm version patch
   npm run publish:safe
   ```

3. Notify users of the issue and fix

## 📝 Notes

- This checklist is version controlled and should be updated when new test cases are identified
- Each team member should maintain their own copy and check off items
- For critical releases, have a second person verify the checklist
- Keep test results for audit purposes

---

Last updated: 2025-08-02
Version: 1.0.0