# v0.5.0 Plan - Release Automation & Workflow Enhancements

**Status:** ✅ COMPLETE (Released v0.5.1 - Dec 30, 2025)
**Target:** After v0.4.0 stabilization (v0.4.0 released Dec 30, 2025)
**Theme:** Release automation, workflow variables, enhanced CLI

---

## Phase 1: Release Commands (`ait release`)

Streamline PyPI and Homebrew releases with dedicated CLI commands.

### Commands

| Command | Description | Status |
|---------|-------------|--------|
| `ait release check` | Pre-release validation (version, tests, changelog) | ✅ Complete |
| `ait release status` | Show current release state and pending changes | ✅ Complete |
| `ait release pypi` | Build and publish to PyPI | ✅ Complete |
| `ait release homebrew` | Update Homebrew formula in tap | ✅ Complete |
| `ait release tag` | Create annotated git tag | ✅ Complete |
| `ait release notes` | Generate release notes from commits | ✅ Complete |
| `ait release full` | Full release workflow (check → tag → pypi → homebrew) | ✅ Complete |

### `ait release check`

Validates release readiness:

```bash
ait release check

# Output:
Release Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Version consistency (0.4.0)
  - pyproject.toml: 0.4.0
  - __init__.py: 0.4.0
  - CHANGELOG.md: [0.4.0] entry found
✓ Tests passing (424/424)
✓ No uncommitted changes
✓ On main branch
✗ Tag v0.4.0 already exists

Ready to release: YES (use --force to re-release)
```

### `ait release status`

Shows release state:

```bash
ait release status

# Output:
Release Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current: v0.4.0 (PyPI, Homebrew, GitHub)
Latest tag: v0.4.0
Commits since tag: 3

Pending changes:
  - docs: streamline CLAUDE.md
  - fix: minor typo
  - feat: add new feature

Suggested next version: v0.4.1 (patch)
```

### `ait release pypi`

Build and publish:

```bash
ait release pypi

# Steps:
# 1. Run release check
# 2. Build with uv build
# 3. Publish with uv publish (or twine)
# 4. Verify on PyPI
```

### `ait release homebrew`

Update Homebrew formula:

```bash
ait release homebrew

# Steps:
# 1. Get PyPI package URL and SHA256
# 2. Update formula in homebrew-tap repo
# 3. Commit and push formula
# 4. Optionally test with `brew install --build-from-source`
```

### `ait release full`

Complete release workflow:

```bash
ait release full 0.5.0

# Interactive workflow:
# 1. Bump version in pyproject.toml, __init__.py
# 2. Update CHANGELOG.md (or prompt to edit)
# 3. Commit version bump
# 4. Create annotated tag
# 5. Push to origin with tags
# 6. Create GitHub Release
# 7. Wait for PyPI publish (CI)
# 8. Update Homebrew formula
# 9. Verify installation
```

### Implementation Notes

- Use `uv build` and `uv publish` for PyPI
- Parse `pyproject.toml` with `tomllib` (Python 3.11+) or `tomli`
- Use `gh` CLI for GitHub releases
- Store Homebrew tap path in config: `~/.config/aiterm/config.toml`

---

## Phase 2: Workflow Variables & Templates

Enhance workflows with variable substitution and templates.

### Workflow Variables

```yaml
# ~/.config/aiterm/workflows/deploy.yaml
name: deploy
description: Deploy to production
variables:
  environment: staging  # default
  version: ${VERSION}   # from env
commands:
  - echo "Deploying ${version} to ${environment}"
  - ./deploy.sh --env ${environment}
```

```bash
# Override variables
ait workflows run deploy --var environment=production --var version=1.2.3
```

### Workflow Templates

```bash
# Create from template
ait workflows template list
ait workflows template apply python-release

# Templates:
# - python-release: lint → test → build → pypi
# - node-release: lint → test → build → npm
# - docs-deploy: build → deploy-docs
# - full-ci: format → lint → test → build
```

---

## Phase 3: Workflow Scheduling (Future)

Run workflows on schedule or triggers.

```bash
# Schedule workflow
ait workflows schedule add "test" --cron "0 9 * * *"  # Daily at 9am
ait workflows schedule list
ait workflows schedule remove test

# Trigger on file change (watch mode)
ait workflows watch test --pattern "src/**/*.py"
```

---

## Phase 4: AI-Assisted Workflows (Future)

Intelligent workflow suggestions based on project context.

```bash
# Suggest workflows for current project
ait workflows suggest

# Output:
Suggested Workflows for aiterm (Python)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Based on your project structure:

1. pre-commit: format + lint + test
   Reason: Found ruff.toml, pytest in pyproject.toml

2. docs-preview: docs-serve
   Reason: Found mkdocs.yml

3. release: check + pypi + homebrew
   Reason: Found Homebrew formula reference

Create these? [y/N]
```

---

## Priority Order

| Phase | Priority | Effort | Value |
|-------|----------|--------|-------|
| 1. Release Commands | High | Medium | High - Automates manual release process |
| 2. Workflow Variables | Medium | Low | Medium - More flexible workflows |
| 3. Scheduling | Low | Medium | Low - Nice to have |
| 4. AI Suggestions | Low | High | Medium - Helpful for new users |

---

## Success Criteria

### v0.5.0 MVP
- [x] `ait release check` validates release readiness
- [x] `ait release status` shows current state
- [x] `ait release pypi` publishes to PyPI
- [x] `ait release tag` creates annotated tags
- [x] `ait release notes` generates release notes
- [x] `ait release full` runs complete workflow
- [x] Tests for all release commands (55 tests passing)
- [x] Documentation updated

### Stretch Goals
- [x] `ait release homebrew` updates tap
- [ ] Workflow variables support
- [ ] At least 3 workflow templates

---

## Dependencies

- `uv` for building/publishing
- `gh` CLI for GitHub releases
- `tomllib`/`tomli` for TOML parsing
- Homebrew tap repo access

---

## Related

- v0.4.0: Workflow foundation (craft, workflows, chaining)
- Craft plugin: `/craft:dist:homebrew`, `/craft:check release`
- Current manual workflow documented in CLAUDE.md
