# Deploy UTM Builder Skill - Development Tracker

This document tracks the development progress of the `deploy-utm-builder` Claude skill for deploying the Simple UTM Builder plugin to WordPress.org.

## Overview

**Skill Name:** `deploy-utm-builder`
**Location:** `.claude/skills/deploy-utm-builder/`
**Purpose:** Automate WordPress.org SVN deployment for the UTM Builder plugin
**Status:** In Development - Requires Audit Before Production Use

---

## Current Progress

### Completed

- [x] Initial skill structure created
- [x] SKILL.md with 8-phase deployment workflow (Phase 0-7)
- [x] .env.example template for credentials and paths
- [x] **Phase 0: Environment Setup & SVN Checkout (NEW)**
- [x] Phase 1: Pre-flight checks (version matching, changelog, code audit)
- [x] Phase 2: SVN repository preparation
- [x] Phase 3: Change comparison and verification gate
- [x] Phase 4: Deploy to trunk workflow
- [x] Phase 5: Tag release workflow
- [x] Phase 6: readme.txt update and release
- [x] Phase 7: Post-deployment verification
- [x] Error handling documentation
- [x] Rollback procedure documentation
- [x] Dry-run test completed (Phases 1-3)
- [x] **Fixed hardcoded paths - now uses environment variables**
- [x] **Added SVN checkout verification/creation**

### Test Run Results (2026-01-05)

**Environment:**
- SVN Path: `/Users/nick/Code/SeedProd/utm-builder-svn`
- SVN URL: `https://plugins.svn.wordpress.org/utm-builder`
- Current SVN Revision: 3432852
- Last Changed: 2025-07-10 by nickkimuliam

**Pre-flight Checks:**
- [x] Environment variables loaded from .env
- [x] Version numbers match (1.0.0 across all files)
- [x] Changelog entry exists for version 1.0.0
- [x] Code audit passed (no debug code, no localhost URLs, no TODOs)
- [x] Superglobals properly sanitized

**Change Comparison:**
- Files to ADD: 1 (`uninstall.php`)
- Files MODIFIED: 4 (`class-sutm-admin.php`, `main-page.php`, `sutm-admin.css`, `readme.txt`)
- Files to REMOVE: 2 (`.DS_Store` files - cleanup)

---

## Known Issues & Required Fixes

### Critical (Must Fix Before Production)

1. ~~**Hardcoded Paths**~~ **FIXED**
   - ~~Current: Paths like `/Users/nick/Code/SeedProd/...` are hardcoded~~
   - ~~Solution: Add `UTM_BUILDER_SOURCE_PATH` to .env and use throughout skill~~
   - **Status:** Now uses `$UTM_BUILDER_SOURCE_PATH` environment variable

2. ~~**Missing First-Time SVN Checkout**~~ **FIXED**
   - ~~Current: Assumes SVN repo already exists locally~~
   - ~~Solution: Add Phase 0 to check/create SVN checkout~~
   - **Status:** Phase 0 now includes SVN checkout verification/creation

3. **SVN Password Visibility** (Low Risk)
   - Current: Password passed on command line (`--password $UTM_BUILDER_SVN_PASSWORD`)
   - Impact: Visible in process listings and shell history
   - Mitigation: Password is optional - SVN can use cached credentials
   - Future: Consider `--password-from-stdin` for enhanced security

### Medium Priority

4. ~~**No Pre-Start SVN Cleanliness Check**~~ **FIXED**
   - ~~Current: Doesn't verify SVN working copy is clean before starting~~
   - **Status:** Step 0.4 now checks for uncommitted changes

5. **Tag Exists Error Handling**
   - Current: Shows error but no clear resolution
   - Impact: Developer stuck without guidance
   - Solution: Offer options: (a) increment version, (b) delete existing tag, (c) abort

6. **Screenshots/Assets Folder**
   - Current: No handling for WordPress.org assets (screenshots, banners)
   - Impact: Missing plugin page images
   - Solution: Add assets folder sync to SVN assets/ directory

### Low Priority

7. **Changelog Validation**
   - Current: Only checks if entry exists, not content quality
   - Enhancement: Could validate changelog format and completeness

8. **Dry-Run Mode**
   - Current: Not explicitly documented as a mode
   - Enhancement: Add explicit dry-run documentation

---

## Environment Variables

### Current (.env.example)

```bash
# Paths
UTM_BUILDER_SOURCE_PATH=~/Code/SeedProd/sp-dev-two/wp-content/plugins/utm-builder
UTM_BUILDER_SVN_PATH=~/Code/SeedProd/utm-builder-svn
UTM_BUILDER_SVN_URL=https://plugins.svn.wordpress.org/utm-builder

# Credentials
UTM_BUILDER_SVN_USERNAME=your-wporg-username
UTM_BUILDER_SVN_PASSWORD=your-wporg-password  # Optional - SVN can cache credentials
```

### Variable Reference

| Variable | Required | Description |
|----------|----------|-------------|
| `UTM_BUILDER_SOURCE_PATH` | Yes | Path to local plugin source code |
| `UTM_BUILDER_SVN_PATH` | Yes | Path to local SVN checkout |
| `UTM_BUILDER_SVN_URL` | Yes | WordPress.org SVN repository URL |
| `UTM_BUILDER_SVN_USERNAME` | Yes | WordPress.org username |
| `UTM_BUILDER_SVN_PASSWORD` | No | WordPress.org password (can use SVN caching) |

---

## Deployment Workflow Summary

| Phase | Description | Commits to SVN |
|-------|-------------|----------------|
| 0 | Environment Setup & SVN Checkout | None |
| 1 | Pre-Flight Checks | None |
| 2 | Prepare SVN Repository | None |
| 3 | Compare Changes & Approval | None |
| 4 | Deploy to Trunk | "Staging vX.X.X" |
| 5 | Tag the Release | "Tagging vX.X.X" |
| 6 | Update readme.txt | "Releasing vX.X.X" |
| 7 | Post-Deployment Verification | None |

---

## Files in Skill

```
.claude/skills/deploy-utm-builder/
├── SKILL.md        # Main skill workflow (509 lines)
├── .env.example    # Environment variable template
└── .env            # Developer's local credentials (gitignored)
```

---

## Testing Checklist

### Before First Production Deployment

- [ ] Fix hardcoded paths issue
- [ ] Add SVN checkout verification/creation
- [ ] Test with a version bump (not same version)
- [ ] Test tag creation on new version
- [ ] Verify WordPress.org displays correct version after deployment
- [ ] Test rollback procedure
- [ ] Document SVN password security approach

### Each Deployment

- [ ] Run Phases 1-3 (dry run)
- [ ] Review all diffs
- [ ] Verify changelog matches changes
- [ ] Get explicit approval before Phase 4
- [ ] Verify on WordPress.org after completion

---

## Session Continuation Notes

If starting a new Claude session, here's what you need to know:

1. **Skill Location:** `.claude/skills/deploy-utm-builder/SKILL.md`
2. **Current State:** Skill written but needs fixes before production use
3. **Last Test:** Dry-run of Phases 1-3 completed successfully
4. **Next Steps:** Fix hardcoded paths, add SVN checkout handling
5. **UTM Builder Plugin:** Located at `wp-content/plugins/utm-builder/`

### Quick Resume Commands

```bash
# Check skill files
ls -la .claude/skills/deploy-utm-builder/

# View current .env
cat .claude/skills/deploy-utm-builder/.env

# Test environment loading
source .claude/skills/deploy-utm-builder/.env && echo $UTM_BUILDER_SVN_PATH
```

---

## Related Documentation

- WordPress.org Plugin SVN: https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/
- Plugin readme.txt format: https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/
- Plugin assets: https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/

---

## Changelog

### 2026-01-05 (Session 2)
- Fixed hardcoded paths - now uses `$UTM_BUILDER_SOURCE_PATH` environment variable
- Added Phase 0: Environment Setup & SVN Checkout
- Added Step 0.3: SVN checkout verification/creation for new developers
- Added Step 0.4: SVN working copy cleanliness check
- Updated .env.example with all required variables
- Updated .env with new path variables
- Updated this tracking document with fixes

### 2026-01-05 (Session 1)
- Initial skill creation
- Added 7-phase deployment workflow
- Completed dry-run test of Phases 1-3
- Identified issues requiring fixes
- Created this tracking document

---

*Last Updated: 2026-01-05*
