# aiterm v0.4.0 Plan: Workflow Automation & Craft Integration

**Created:** 2025-12-26
**Updated:** 2025-12-31
**Target:** v0.4.0
**Theme:** Workflow automation through aiterm CLI + craft plugin integration

---

## Phase Status

| Phase | Description | Status |
|-------|-------------|--------|
| **Phase 0** | craft v1.5.0 Enhancement | ✅ COMPLETE |
| **Phase 0.5** | craft Mermaid & Worktree Support | ✅ COMPLETE |
| **Phase 0.6** | Ghostty Multi-Terminal Support | ✅ COMPLETE |
| **Phase 0.7** | Quick Wins (flow-cli style) | ✅ COMPLETE |
| **Phase 0.8** | Ghostty Enhancements (iTerm2 parity) | ✅ COMPLETE |
| **Phase 1** | Workflow Templates | ⏳ Planned |
| **Phase 1b** | Feature Workflow Commands | ✅ COMPLETE |
| **Phase 1c** | CLI Test Runner | ⏳ Planned |
| **Phase 1d** | Workflow Enforcement | ⏳ Waiting (flow-cli) |
| **Phase 2** | Craft Plugin Management | ✅ COMPLETE |
| **Phase 3** | Session-Aware Workflows | ✅ COMPLETE |
| **Phase 4** | AI Recipe Intelligence | ⏳ Future |

---

## Overview

v0.4.0 bridges the gap between:
- **aiterm CLI** - Terminal setup, context detection, settings management
- **craft plugin** - Claude Code commands, skills, and orchestration (v1.5.0)

**Goal:** Seamless developer workflows from terminal to Claude Code.

---

## Current State

### aiterm v0.6.1 (Current - Dec 31, 2025)
- **v0.6.1**: CI/CD improvements, craft v1.14.0 integration, Homebrew automation verified
- **v0.6.0**: Interactive tutorial system
- **v0.5.x**: Release automation improvements
- **v0.3.12**: Fixed version display, CI workflow fixes
- **v0.3.11**: Documentation updates for config and terminal features
- **v0.3.9-0.3.10**: Ghostty terminal support, XDG config paths
- **v0.3.6-0.3.8**: IDE integrations, session coordination, curl installer
- IDE integrations (VS Code, Cursor, Zed, Positron, Windsurf)
- Session coordination (hook-based tracking, conflict detection)
- MCP server management
- Context detection (8 project types)
- curl installer (`install.sh` with auto-detection)
- Dogfooding commands (`hello`, `goodbye`, `info`)
- Ghostty terminal backend (themes, fonts, config)
- XDG-compliant config paths (`~/.config/aiterm/`)
- ~380 tests passing

### craft v1.14.0 ✅ (Latest - Dec 31, 2025)

| Metric | v1.5.0 | v1.14.0 | Change |
|--------|--------|---------|--------|
| Commands | 53 | **72** | +19 |
| Agents | 7 | **8** | +1 |
| Skills | 13 | **21** | +8 |

**v1.14.0 Highlights (Homebrew Automation):**
- `homebrew-workflow-expert` skill
- `homebrew-setup-wizard` skill
- `homebrew-multi-formula` skill
- Enhanced `/craft:dist:homebrew` with 8 subcommands
- Formula validation, batch releases, dependency ordering

**Added since v1.2.0:**
- 5 documentation agents (docs-architect, tutorial-engineer, api-documenter, reference-builder, mermaid-expert)
- 5 documentation/testing skills (changelog, ADR, OpenAPI, cli-test-strategist, + 1 more)
- 7 new commands: `docs:generate`, `docs:api`, `test:cli-gen`, `test:cli-run`, `dist:homebrew`, `dist:curl-install`, + 1 more

**See:** `PROPOSAL-craft-enhancements-2025-12-26.md` for original specification

---

## v0.4.0 Features

### Phase 0: craft v1.5.0 Enhancement ✅ COMPLETE
**Goal:** Upgrade craft plugin before starting aiterm workflow features

**Status:** ✅ COMPLETE (Dec 27, 2025)

**Delivered:**
1. ✅ Port 5 documentation agents from documentation-generation plugin
2. ✅ Port 5 documentation/testing skills (changelog, ADR, OpenAPI, cli-test, distribution)
3. ✅ Create `docs:generate` command (routes to agents)
4. ✅ Create `docs:api` command (OpenAPI generation)
5. ✅ Create `test:cli-gen` command (CLI test suite generation)
6. ✅ Create `test:cli-run` command (CLI test execution)
7. ✅ Create `dist:homebrew` command (Homebrew formula validation)
8. ✅ Create `dist:curl-install` command (curl installer generation)
9. ✅ Update craft README for v1.5.0
10. ✅ Validate all new components work correctly

**Bonus:** Distribution commands added in v1.5.0 (not in original plan)

### Phase 0.5: craft Mermaid & Worktree Support (Priority: High)
**Goal:** Enhance craft plugin with learnings from Git Worktrees Guide session
**Status:** ✅ COMPLETE (Dec 28, 2025)

**See:** `PROPOSAL-craft-worktree-mermaid-2025-12-28.md` for full specification

#### Quick Wins (~1 hour total) - COMPLETE

| Task | Effort | Status |
|------|--------|--------|
| Add Mermaid config check to `craft:site:status` | 15m | [x] |
| Create Mermaid linter skill | 20m | [x] |
| Update `docs:generate` with Mermaid guidelines | 15m | [x] |
| Add worktree detection to `craft:check` | 20m | [x] |

#### Medium Effort (~2.5 hours) - COMPLETE

| Task | Effort | Status |
|------|--------|--------|
| Create Mermaid diagram templates command | 1h | [x] |
| Implement worktree setup command (`craft:git:worktree`) | 1.5h | [x] |

**Deliverables:**
1. ✅ Mermaid config validation in site:status (prevents "diagrams as code" issue)
2. ✅ Mermaid linter skill for syntax/length validation
3. ✅ Worktree detection for context-aware commands
4. ✅ Mermaid diagram templates (dependency, workflow, architecture, comparison, sequence, state)
5. ✅ Worktree setup automation (stash → checkout → create → pop → install)

**craft v1.8.0 Ready:**
- +1 skill (mermaid-linter) ✅
- +2 commands (git:worktree, docs:mermaid) ✅
- Enhanced: site:status, check, docs:generate ✅

### Phase 0.6: Ghostty Multi-Terminal Support (Priority: Medium)
**Goal:** Add Ghostty as second fully-supported terminal (after iTerm2)
**Status:** ✅ COMPLETE (Dec 29, 2025)

**Deliverables:**
1. ✅ Terminal detection system (6 terminals: iTerm2, Ghostty, Kitty, Alacritty, WezTerm, Apple Terminal)
2. ✅ Ghostty backend (250 lines): config parsing, theme management, fonts
3. ✅ Ghostty CLI (280 lines): status, config, theme, font, set commands
4. ✅ 14 built-in themes with auto-reload
5. ✅ 19 new tests (all passing)
6. ✅ Documentation: `docs/guide/terminals.md`

**New CLI Commands:**
```bash
ait ghostty status              # Detection and version info
ait ghostty config [--edit]     # Show/edit config
ait ghostty theme list|apply|show  # Theme management
ait ghostty font show|set       # Font configuration
ait ghostty set <key> <value>   # Generic config setting
```

### Phase 0.7: Quick Wins - flow-cli Style (Priority: High)
**Goal:** Adopt flow-cli UX patterns for better ADHD-friendly experience
**Status:** ⏳ Next up

**See:** `IDEAS.md` for full details

#### Quick Wins (~3.5 hours total)

| Task | Effort | Status |
|------|--------|--------|
| Add `ait ghost` aliases | 15m | [ ] |
| Terminal-aware `ait switch` | 30m | [ ] |
| `ait terminals doctor` command | 1h | [ ] |
| flow-cli help style for all commands | 2h | [ ] |

**Ghost Aliases:**
```bash
ait ghost           # → ait ghostty status
ait ghost theme     # → ait ghostty theme list
ait ghost config    # → ait ghostty config
```

**Terminals Doctor:**
```bash
ait terminals doctor           # Check all terminal configs
ait terminals doctor ghostty   # Check specific terminal
ait terminals doctor --fix     # Auto-fix common issues
```

**Help Style (flow-cli pattern):**
```
╭─────────────────────────────────────────────────╮
│  🎯 COMMAND NAME                                │
╰─────────────────────────────────────────────────╯

MOST COMMON:
  command arg     Description

QUICK EXAMPLES:
  $ command foo   Do foo thing

See also: man command, related-command
```

### Phase 0.8: Ghostty Enhancements - iTerm2 Parity (Priority: Medium)
**Goal:** Full parity with iTerm2 integration for power users
**Status:** ✅ COMPLETE (Dec 30, 2025)

**See:** `docs/specs/SPEC-ghostty-enhancements-2025-12-30.md` for full specification

#### Sub-phases (4 phases from spec)

| Phase | Feature | Effort | Status | Commands |
|-------|---------|--------|--------|----------|
| 0.8.1 | Profile management | ~2h | ✅ DONE | `profile list/show/apply/create/delete` |
| 0.8.2 | Config backup | ~1h | ✅ DONE | `backup`, `restore` |
| 0.8.3 | Keybind management | ~2h | ✅ DONE | `keybind list/add/remove/preset` |
| 0.8.4 | Session control | ~3h | ✅ DONE | `session save/restore/list/split` |

**Completed (Dec 30, 2025):**
- ✅ GhosttyProfile dataclass with config serialization
- ✅ Profile storage in `~/.config/ghostty/profiles/*.conf`
- ✅ Profile CRUD operations (list, get, save, delete, create_from_current, apply)
- ✅ Config backup with timestamped files
- ✅ Backup restore with pre-restore safety
- ✅ CLI commands: `ait ghostty profile list/show/create/apply/delete`
- ✅ CLI commands: `ait ghostty backup`, `ait ghostty restore`
- ✅ GhosttyKeybind dataclass with config parsing
- ✅ Keybind presets (vim, emacs, tmux, macos)
- ✅ CLI commands: `ait ghostty keybind list/add/remove/preset`
- ✅ GhosttySession dataclass with JSON storage
- ✅ Session storage in `~/.config/ghostty/sessions/*.json`
- ✅ CLI commands: `ait ghostty session list/show/save/restore/delete/split`
- ✅ 96 Ghostty tests (34 new for Phase 0.8.3-0.8.4)

#### New Commands

```bash
# Profile management (hybrid: config files + runtime)
ait ghostty profile list              # List profiles
ait ghostty profile show <name>       # Show profile details
ait ghostty profile apply <name>      # Apply a profile
ait ghostty profile create <name>     # Create from current
ait ghostty profile delete <name>     # Delete a profile

# Keybind management
ait ghostty keybind list              # List current bindings
ait ghostty keybind add <key> <action> # Add keybinding
ait ghostty keybind remove <key>      # Remove keybinding
ait ghostty keybind preset <name>     # Apply preset (vim/emacs)

# Session control
ait ghostty session save <name>       # Save session layout
ait ghostty session restore <name>    # Restore session
ait ghostty session list              # List saved sessions
ait ghostty session split <dir>       # Split pane (h/v)

# Config backup (matching claude backup pattern)
ait ghostty backup                    # Create timestamped backup
ait ghostty restore [backup]          # Restore from backup
```

#### Open Questions (from spec)
- [ ] Does Ghostty support OSC escape sequences for runtime config changes?
- [ ] Should profiles be stored as separate files or in a single profiles.toml?
- [ ] What session layout format to use? (JSON vs TOML vs custom)
- [ ] Should keybind presets be bundled or fetched from a repository?

### Phase 1: Workflow Templates (Priority: High)
**Goal:** Pre-configured workflows that chain aiterm + craft commands

```bash
# Example: Full stack development workflow
ait workflow apply fullstack

# Expands to:
# 1. aiterm: Context detection, profile switching
# 2. craft: /craft:check → /craft:test:run → /craft:git:sync
```

**New CLI Module:** `src/aiterm/cli/workflow_recipes.py`

| Command | Description |
|---------|-------------|
| `ait recipes list` | List available workflow recipes |
| `ait recipes show <name>` | Show recipe details |
| `ait recipes apply <name>` | Apply a recipe to current project |
| `ait recipes create` | Interactive recipe builder |
| `ait recipes export` | Export recipe as shareable config |

**Built-in Recipes:**
1. `fullstack` - Full-stack development (test, lint, commit)
2. `release` - Release preparation (/craft:check --for release)
3. `feature` - Feature development flow
4. `debug` - Debugging session setup
5. `docs` - Documentation workflow
6. `r-dev` - R package development (integrates with rforge v0.1.0 tools: `rforge_plan`, `rforge_deps`)

### Phase 1b: Feature Workflow Commands (Priority: High)
**Goal:** Rich CLI commands for feature branch + worktree management

**Split from flow-cli:** Shell aliases handled by flow-cli, rich visualization by aiterm

```bash
# Visibility commands (Phase 1b.1)
ait feature status        # Pipeline visualization
ait feature list          # Features with worktree paths

# Automation commands (Phase 1b.2)
ait feature start <name>  # Create branch + worktree + deps
ait feature cleanup       # Remove merged features
ait feature promote       # Rich PR creation
ait feature release       # Dev → main with validation
```

**New CLI Module:** `src/aiterm/cli/feature.py`

| Command | Description |
|---------|-------------|
| `ait feature status` | Show feature pipeline visualization |
| `ait feature list` | List features with worktree locations |
| `ait feature start <name>` | Create feature branch + worktree + install deps |
| `ait feature cleanup` | Interactive cleanup of merged features |
| `ait feature promote` | Create PR to dev with validation |
| `ait feature release` | Create PR dev → main |

**Relationship to flow-cli:**
| Need | flow-cli | aiterm |
|------|----------|--------|
| Quick branch | `gfs` | - |
| Quick PR | `gfp` | - |
| Pipeline view | - | `ait feature status` |
| Full setup | - | `ait feature start` |

**See:** `docs/proposals/FEATURE-WORKFLOW-OWNERSHIP.md`

### Phase 1c: CLI Test Runner (Priority: Medium)
**Goal:** Run interactive tests in split terminal from Claude Code

```bash
ait test interactive                    # New window (default)
ait test interactive --split right      # Vertical split
ait test interactive --split below      # Horizontal split
ait test interactive --split tab        # New tab
ait test interactive --terminal ghostty # Force specific terminal
```

**Terminal Support:**
| Terminal | Splits | Tabs | Windows |
|----------|--------|------|---------|
| **Ghostty** (default) | ✅ | ✅ | ✅ |
| **iTerm2** | ✅ | ✅ | ✅ |
| **Terminal.app** | ❌ | ✅ | ✅ |

**Implementation:** `src/aiterm/cli/test_runner.py`
**Prototype:** `scripts/run-interactive-tests.sh` (already implemented)

### Phase 2: Craft Plugin Management (Priority: Medium)
**Goal:** Manage craft plugin from aiterm CLI

```bash
# Install/update craft
ait craft install
ait craft update

# Sync craft with aiterm context
ait craft sync              # Auto-configure based on project type

# Run craft commands from terminal
ait craft run check         # Same as /craft:check in Claude Code
ait craft run test:run release
```

**New CLI Module:** `src/aiterm/cli/craft.py`

| Command | Description |
|---------|-------------|
| `ait craft status` | Show craft plugin status |
| `ait craft install` | Install craft plugin |
| `ait craft update` | Update craft plugin |
| `ait craft sync` | Sync with project context |
| `ait craft run <cmd>` | Execute craft command |
| `ait craft list` | List available craft commands |

### Phase 3: Session-Aware Workflows (Priority: Medium)
**Goal:** Workflows that respect active Claude Code sessions

```bash
# Check if Claude Code is active before running
ait workflow run release --require-session

# Workflows can interact with session task
ait sessions task "Running release workflow"
ait workflow run release
# Task auto-updates as workflow progresses
```

**Integration Points:**
- Hook into `~/.claude/sessions/active/` for session awareness
- Update session task field during workflow execution
- Prevent conflicting workflows on same project

### Phase 4: AI Recipe Intelligence (Priority: Low)
**Goal:** AI-powered recipe suggestions based on project state

```bash
# Suggest next steps based on context
ait recipes suggest

# Output:
# Based on current state:
# - 3 uncommitted changes
# - Tests passing
# - On feature branch
#
# Suggested recipe: 'commit-flow'
# Run: ait recipes apply commit-flow
```

---

## Implementation Timeline

### Week 1-2: Phase 1 (Workflow Templates)
- [ ] Create `workflow_recipes.py` CLI module
- [ ] Define recipe format (YAML/JSON)
- [ ] Implement 6 built-in recipes
- [ ] Add recipe storage in `~/.config/aiterm/recipes/`
- [ ] Write tests (target: 20+ tests)

### Week 3: Phase 2 (Craft Management)
- [ ] Create `craft.py` CLI module
- [ ] Implement install/update/sync commands
- [ ] Add craft command passthrough (`ait craft run`)
- [ ] Write tests (target: 15+ tests)

### Week 4: Phase 3 (Session Integration)
- [ ] Add session checks to workflow runner
- [ ] Implement task auto-update during workflows
- [ ] Add conflict prevention
- [ ] Write tests (target: 10+ tests)

---

## Recipe Format

```yaml
# ~/.config/aiterm/recipes/release.yaml
name: release
description: Release preparation workflow
version: 1.0.0

# Prerequisites
requires:
  - clean_git: true
  - tests_passing: true
  - craft_installed: true

# Steps
steps:
  - name: pre-flight
    type: aiterm
    command: ait sessions prune  # Clean stale sessions

  - name: check
    type: craft
    command: /craft:check --for release

  - name: test
    type: craft
    command: /craft:test:run release

  - name: audit
    type: craft
    command: /craft:code:deps-audit

  - name: changelog
    type: craft
    command: /craft:docs:changelog

# Post-completion
on_success:
  - notify: "Release checks complete"
  - update_task: "Ready for release"
```

---

## Success Criteria

### v0.4.0 MVP
- [ ] 6+ built-in recipes working
- [ ] Recipe list/show/apply commands functional
- [ ] Craft status/install/sync commands working
- [ ] Session-aware workflow execution
- [ ] 45+ new tests
- [ ] Documentation updated

### Quality Metrics
- [ ] 85%+ code coverage on new modules
- [ ] All existing tests passing (~380 tests)
- [ ] No regressions in v0.3.6 features

---

## Files to Create

```
src/aiterm/
├── cli/
│   ├── workflow_recipes.py    # Recipe management
│   └── craft.py               # Craft plugin management
├── recipes/
│   ├── __init__.py
│   ├── loader.py              # Recipe loading/parsing
│   ├── runner.py              # Recipe execution
│   └── templates/             # Built-in recipes
│       ├── fullstack.yaml
│       ├── release.yaml
│       ├── feature.yaml
│       ├── debug.yaml
│       ├── docs.yaml
│       └── r-dev.yaml
tests/
├── test_recipes.py
└── test_craft_integration.py
docs/
├── guide/workflow-recipes.md
└── reference/REFCARD-RECIPES.md
```

---

## Dependencies

- **craft plugin v1.5.0** ✅ - Required for command integration (Phase 0 complete)
- **Session hooks** ✅ - For session-aware workflows (already in v0.3.0)
- **PyYAML** ✅ - For recipe parsing (already a dependency)

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| craft not installed | Graceful fallback, install prompt |
| Recipe execution fails mid-way | Rollback support, resume capability |
| Version mismatch | Version compatibility checks |

---

## Notes

- Recipes should be project-portable (no absolute paths)
- User recipes override built-in recipes with same name
- Consider marketplace for community recipes in future

---

## Session Notes

### 2025-12-30 Session (Part 2)

**Completed:**
- **Phase 0.7: Quick Wins**
  - `ait ghost` aliases for quick Ghostty access (status/theme/config/font)
  - Terminal-aware `ait switch` (auto-detects iTerm2/Ghostty/etc)
  - Shows terminal type in context detection output
- **Phase 1b: Feature Workflow Commands**
  - `ait feature status` - Rich pipeline visualization
  - `ait feature list` - Detailed feature branch listing
  - `ait feature start` - Full automation (branch + worktree + deps)
  - `ait feature cleanup` - Interactive merged branch cleanup
  - 17 new tests (all passing)

**Stats:**
- +894 lines of code
- 3 files changed
- 17 new tests

**Suggested Next Steps:**
1. **Workflow Templates** - Start Phase 1: `ait recipes list/show/apply`
2. **Session Integration** - Connect feature workflow with session tracking
3. **Docs Update** - Document new feature workflow commands

---

### 2025-12-31 Session: Homebrew Automation Complete

**Completed:**
- **craft v1.14.0 Released** - Full Homebrew automation suite
  - `homebrew-setup-wizard` skill (381 lines)
  - `homebrew-multi-formula` skill (354 lines)
  - `/craft:dist:homebrew` with 8 subcommands (formula, workflow, validate, token, setup, update-resources, release-batch, deps)
- **aiterm v0.6.1 Released** - End-to-end Homebrew automation test
  - Tag push → Release → Workflow → PR → Auto-merge → Formula updated
  - Both uv and Homebrew installations verified at v0.6.1
- **Full automation flow verified** on aiterm, flow-cli, nexus-cli, atlas

**Stats:**
- craft: 72 commands, 8 agents, 21 skills
- aiterm: v0.6.1 (Homebrew + PyPI)

**Priority Next Steps:**
1. **Feature Workflow** - Implement `ait feature status/start/cleanup` (Phase 1b complete, polish needed)
2. **PyPI Release Automation** - Similar workflow to Homebrew (tag → workflow → PyPI publish)
3. **Workflow Templates** - Start Phase 1: `ait recipes list/show/apply`

---

### 2025-12-30 Session (Part 1)

**Completed:**
- v0.3.11 and v0.3.12 released to PyPI
- Homebrew tap updated for both versions
- Documentation comprehensively updated (User Guide, terminals.md, REFCARD)
- Fixed `__version__` mismatch between `__init__.py` and `pyproject.toml`
- Fixed GitHub Actions checkout ref for `workflow_dispatch` triggers
- mkdocs navigation updated (added terminals.md, troubleshooting guide)
- Docs deployed to GitHub Pages
