aidevops 2.52.1

package/.agent/tools/task-management/beads.md

@@ -0,0 +1,336 @@
+---
+name: beads
+description: This subagent should only be called manually by the user.
+mode: subagent
+---
+
+# Beads - Task Graph Visualization
+
+Task dependency tracking and graph visualization for TODO.md and PLANS.md.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `bd` | Beads CLI |
+| `bd init` | Initialize Beads in project |
+| `bd create "task"` | Create a task |
+| `bd list` | List all tasks |
+| `bd ready` | Show tasks with no blockers |
+| `bd graph <id>` | Show dependency graph for issue |
+| `bd dep add <id2> <id1>` | Make id2 depend on id1 |
+| `bd close <id>` | Close a task |
+| `beads-sync-helper.sh push` | Sync TODO.md → Beads |
+| `beads-sync-helper.sh pull` | Sync Beads → TODO.md |
+| `todo-ready.sh` | Show unblocked tasks (from TODO.md) |
+
+## Architecture
+
+```text
+TODO.md / PLANS.md (source of truth)
+         ↓ push
+    .beads/beads.db (SQLite + JSONL)
+         ↓
+    Graph visualization (bd CLI, TUIs)
+```
+
+**Key principle**: aidevops markdown files are the source of truth. Beads syncs from them.
+
+## Task ID Format
+
+```markdown
+- [ ] t001 Task description
+- [ ] t001.1 Subtask of t001
+- [ ] t001.1.1 Sub-subtask
+```
+
+## Dependency Syntax
+
+```markdown
+- [ ] t002 Implement feature blocked-by:t001
+- [ ] t003 Deploy blocks:t004,t005
+```
+
+| Syntax | Meaning |
+|--------|---------|
+| `blocked-by:t001` | This task waits for t001 |
+| `blocked-by:t001,t002` | Waits for multiple tasks |
+| `blocks:t003` | This task blocks t003 |
+
+## Sync Commands
+
+### Push (TODO.md → Beads)
+
+```bash
+# Sync current project
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+
+# Sync specific project
+~/.aidevops/agents/scripts/beads-sync-helper.sh push /path/to/project
+```
+
+### Pull (Beads → TODO.md)
+
+```bash
+# Pull changes from Beads
+~/.aidevops/agents/scripts/beads-sync-helper.sh pull
+```
+
+### Status
+
+```bash
+# Check sync status
+~/.aidevops/agents/scripts/beads-sync-helper.sh status
+```
+
+## Ready Tasks
+
+Show tasks with no open blockers:
+
+```bash
+# List ready tasks
+~/.aidevops/agents/scripts/todo-ready.sh
+
+# JSON output
+~/.aidevops/agents/scripts/todo-ready.sh --json
+
+# Count only
+~/.aidevops/agents/scripts/todo-ready.sh --count
+```
+
+## Beads CLI Commands
+
+```bash
+# Initialize
+bd init
+
+# Create task
+bd create "Implement login"
+
+# Create with description
+bd create "Deploy" --description="Deploy to production"
+
+# Add dependency (issue2 depends on issue1)
+bd dep add <issue2-id> <issue1-id>
+
+# List tasks
+bd list
+bd list --status open
+
+# Show graph for an issue
+bd graph <issue-id>
+
+# Show ready tasks (no blockers)
+bd ready
+
+# Close task
+bd close <id>
+
+# MCP server (for AI tools)
+bd mcp
+```
+
+## Conflict Resolution
+
+When both TODO.md and Beads have changes:
+
+1. **Warning displayed** - sync detects conflict
+2. **Manual resolution** - review both sources
+3. **Force push** - `beads-sync-helper.sh push --force`
+4. **Force pull** - `beads-sync-helper.sh pull --force`
+
+## Viewers
+
+| Tool | Type | Features | Install |
+|------|------|----------|---------|
+| `bd` | CLI | Core commands, MCP server | `brew install steveyegge/beads/bd` |
+| `beads_viewer` | TUI | PageRank, critical path, graph analytics | `pip install beads-viewer` |
+| `beads-ui` | Web | Live updates, browser-based | `npm install -g beads-ui` |
+| `bdui` | TUI | React/Ink interface | `npm install -g bdui` |
+| `perles` | TUI | BQL query language | `cargo install perles` |
+
+### Viewer Installation
+
+```bash
+# Core CLI (required)
+brew install steveyegge/beads/bd
+# Or: go install github.com/steveyegge/beads/cmd/bd@latest
+
+# Advanced TUI with graph analytics (Python)
+pip install beads-viewer
+# Repository: https://github.com/Dicklesworthstone/beads_viewer
+
+# Web UI with live updates (Node.js)
+npm install -g beads-ui
+# Or run locally: npx beads-ui
+# Repository: https://github.com/mantoni/beads-ui
+
+# React/Ink TUI (Node.js)
+npm install -g bdui
+# Repository: https://github.com/assimelha/bdui
+
+# BQL query language TUI (Rust)
+cargo install perles
+# Repository: https://github.com/zjrosen/perles
+```
+
+### Running Viewers
+
+```bash
+# Core CLI
+bd list
+bd ready
+bd graph <issue-id>
+
+# beads_viewer - Advanced TUI
+beads-viewer              # Interactive mode
+beads-viewer --pagerank   # Show PageRank scores
+beads-viewer --critical   # Show critical path
+
+# beads-ui - Web interface
+beads-ui                  # Starts on http://localhost:3000
+beads-ui --port 8080      # Custom port
+
+# bdui - React/Ink TUI
+bdui                      # Interactive mode
+
+# perles - BQL queries
+perles                    # Interactive REPL
+perles "SELECT * FROM issues WHERE status = 'open'"
+```
+
+## Installation
+
+```bash
+# Homebrew (macOS/Linux)
+brew install steveyegge/beads/bd
+
+# Go
+go install github.com/steveyegge/beads/cmd/bd@latest
+
+# Or via aidevops setup
+./setup.sh  # Installs bd automatically
+```
+
+## Project Initialization
+
+```bash
+# Enable beads in a project
+aidevops init beads
+
+# This:
+# 1. Creates .beads/ directory
+# 2. Runs bd init
+# 3. Syncs existing TODO.md/PLANS.md
+# 4. Adds .beads to .gitignore
+```
+
+## Integration with Workflows
+
+### Task Lifecycle
+
+Workflow commands automatically update task status:
+
+```text
+Ready/Backlog → In Progress → In Review → Done
+   (branch)       (develop)      (PR)     (merge/release)
+```
+
+| Workflow | Task Status Change | TODO.md Section | Beads Action |
+|----------|-------------------|-----------------|--------------|
+| `/branch create` | → In Progress | Move to `## In Progress` | `beads-sync-helper.sh push` |
+| `/pr create` | → In Review | Move to `## In Review` | `beads-sync-helper.sh push` |
+| `/pr merge` | → Done | Move to `## Done` | `beads-sync-helper.sh push` |
+| `/release` | → Done (all) | Move remaining to `## Done` | `beads-sync-helper.sh push` |
+
+### Task Attributes by Stage
+
+| Stage | Attributes Added |
+|-------|------------------|
+| In Progress | `started:2025-01-15T10:30Z` |
+| In Review | `pr:123` or `pr_url:https://...` |
+| Done | `completed:2025-01-16T14:00Z`, `actual:5h` |
+
+### Git Workflow
+
+```bash
+# Before starting work
+~/.aidevops/agents/scripts/todo-ready.sh  # See what's ready
+
+# After creating branch
+# Move task to ## In Progress, add started:, then:
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+
+# After creating PR
+# Move task to ## In Review, add pr:, then:
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+
+# After merge/release
+# Move task to ## Done, add completed: and actual:, then:
+~/.aidevops/agents/scripts/beads-sync-helper.sh push
+```
+
+### Planning Workflow
+
+1. Add tasks to TODO.md with dependencies
+2. Run `/sync-beads` to update graph
+3. Use `bd graph` to visualize
+4. Run `/ready` to see unblocked tasks
+
+### Slash Commands
+
+| Command | Action |
+|---------|--------|
+| `/ready` | Show tasks with no blockers (Ready section) |
+| `/sync-beads` | Sync TODO.md ↔ Beads |
+| `/branch` | Create branch, move task to In Progress |
+| `/pr` | Create PR, move task to In Review |
+| `/release` | Release version, move tasks to Done |
+
+## TOON Blocks
+
+TODO.md includes TOON blocks for structured data:
+
+```markdown
+<!--TOON:dependencies-->
+t002|blocked-by|t001
+t003|blocks|t004
+<!--/TOON:dependencies-->
+
+<!--TOON:subtasks-->
+t001|t001.1,t001.2
+t001.1|t001.1.1
+<!--/TOON:subtasks-->
+```
+
+## Troubleshooting
+
+### Sync fails
+
+```bash
+# Check lock file
+ls -la .beads/sync.lock
+
+# Remove stale lock
+rm .beads/sync.lock
+
+# Check audit log
+cat .beads/sync.log
+```
+
+### Beads not initialized
+
+```bash
+# Initialize manually
+bd init
+
+# Or reinitialize
+rm -rf .beads && bd init
+```
+
+### Dependencies not showing
+
+Ensure dependency syntax is correct:
+- `blocked-by:t001` (no spaces around colon)
+- Task IDs must exist
+- Use comma for multiple: `blocked-by:t001,t002`

package/.agent/tools/terminal/terminal-title.md

@@ -0,0 +1,251 @@
+---
+description: Terminal tab/window title integration for git context
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+---
+
+# Terminal Title Integration
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Sync terminal tab titles with git repo/branch
+- **Script**: `~/.aidevops/agents/scripts/terminal-title-helper.sh`
+- **Auto-sync**: Runs automatically via `pre-edit-check.sh`
+- **Compatibility**: Most modern terminals (OSC escape sequences)
+
+**Supported Terminals**:
+Tabby, iTerm2, Windows Terminal, Kitty, Alacritty, WezTerm, Hyper, GNOME Terminal, VS Code, Apple Terminal, and most xterm-compatible terminals.
+
+**Commands**:
+
+```bash
+# Sync tab with current repo/branch
+terminal-title-helper.sh sync
+
+# Set custom title
+terminal-title-helper.sh rename "My Project"
+
+# Reset to default
+terminal-title-helper.sh reset
+
+# Check terminal compatibility
+terminal-title-helper.sh detect
+```
+
+**Title Formats** (set via `TERMINAL_TITLE_FORMAT`):
+
+| Format | Example Output |
+|--------|----------------|
+| `repo/branch` (default) | `aidevops/feature/xyz` |
+| `branch` | `feature/xyz` |
+| `repo` | `aidevops` |
+| `branch/repo` | `feature/xyz (aidevops)` |
+
+<!-- AI-CONTEXT-END -->
+
+## Overview
+
+This integration automatically syncs terminal tab/window titles with the current git repository and branch name using OSC (Operating System Command) escape sequences - a standard supported by most modern terminal emulators.
+
+## How It Works
+
+The integration uses OSC escape sequences:
+
+```bash
+# OSC 0 - Set window title and icon name
+printf '\033]0;%s\007' "title"
+
+# OSC 2 - Set window title only  
+printf '\033]2;%s\007' "title"
+```
+
+These sequences are part of the xterm control sequence standard and are supported by virtually all modern terminals.
+
+## Supported Terminals
+
+| Terminal | Platform | Support Level |
+|----------|----------|---------------|
+| **Tabby** | Cross-platform | Full |
+| **iTerm2** | macOS | Full |
+| **Windows Terminal** | Windows | Full |
+| **Kitty** | Cross-platform | Full |
+| **Alacritty** | Cross-platform | Full |
+| **WezTerm** | Cross-platform | Full |
+| **Hyper** | Cross-platform | Full |
+| **GNOME Terminal** | Linux | Full |
+| **Konsole** | Linux | Full |
+| **VS Code Terminal** | Cross-platform | Full |
+| **Apple Terminal** | macOS | Basic |
+| **xterm** | Cross-platform | Full |
+| **tmux/screen** | Cross-platform | With config |
+
+## Automatic Integration
+
+The `pre-edit-check.sh` script automatically syncs the tab title when:
+1. You're in a git repository
+2. You're on a feature branch (not main/master)
+3. The pre-edit check passes
+
+This means your tab title updates automatically when you start working on a branch.
+
+## Manual Usage
+
+### Sync with Git Context
+
+```bash
+~/.aidevops/agents/scripts/terminal-title-helper.sh sync
+# Output: [OK] Tab synced: aidevops/feature/my-feature
+```
+
+### Set Custom Title
+
+```bash
+~/.aidevops/agents/scripts/terminal-title-helper.sh rename "Production Debug"
+# Output: [OK] Tab title set to: Production Debug
+```
+
+### Reset to Default
+
+```bash
+~/.aidevops/agents/scripts/terminal-title-helper.sh reset
+# Output: [OK] Tab title reset to default
+```
+
+### Check Terminal Compatibility
+
+```bash
+~/.aidevops/agents/scripts/terminal-title-helper.sh detect
+# Output: [OK] Running in Kitty terminal (full OSC support)
+# Returns: TABBY, ITERM2, KITTY, WINDOWS_TERMINAL, COMPATIBLE, etc.
+```
+
+## Shell Integration
+
+For automatic tab title updates on every directory change, add to your shell config:
+
+### Bash (`~/.bashrc`)
+
+```bash
+# Update tab title on each prompt
+PROMPT_COMMAND='~/.aidevops/agents/scripts/terminal-title-helper.sh sync 2>/dev/null'
+```
+
+### Zsh (`~/.zshrc`)
+
+```zsh
+# Update tab title before each prompt
+precmd() {
+    ~/.aidevops/agents/scripts/terminal-title-helper.sh sync 2>/dev/null
+}
+```
+
+### Fish (`~/.config/fish/config.fish`)
+
+```fish
+function fish_prompt
+    ~/.aidevops/agents/scripts/terminal-title-helper.sh sync 2>/dev/null
+    # ... rest of your prompt
+end
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TERMINAL_TITLE_FORMAT` | `repo/branch` | Title format |
+| `TERMINAL_TITLE_ENABLED` | `true` | Set to `false` to disable |
+
+### Format Options
+
+```bash
+# Show repo and branch (default)
+export TERMINAL_TITLE_FORMAT="repo/branch"
+# Result: aidevops/feature/xyz
+
+# Show only branch
+export TERMINAL_TITLE_FORMAT="branch"
+# Result: feature/xyz
+
+# Show only repo
+export TERMINAL_TITLE_FORMAT="repo"
+# Result: aidevops
+
+# Show branch with repo in parentheses
+export TERMINAL_TITLE_FORMAT="branch/repo"
+# Result: feature/xyz (aidevops)
+```
+
+## Integration with OpenCode
+
+When using OpenCode with aidevops:
+
+1. **Session names** are synced via `session-rename_sync_branch` tool
+2. **Tab titles** are synced via `terminal-title-helper.sh sync`
+
+Both happen automatically when you create a branch and pass the pre-edit check.
+
+## Troubleshooting
+
+### Tab Title Not Updating
+
+1. Check terminal compatibility:
+
+   ```bash
+   ~/.aidevops/agents/scripts/terminal-title-helper.sh detect
+   ```
+
+2. Verify you're in a git repo:
+
+   ```bash
+   git rev-parse --is-inside-work-tree
+   ```
+
+3. Check if disabled:
+
+   ```bash
+   echo $TERMINAL_TITLE_ENABLED
+   ```
+
+### Title Shows Wrong Format
+
+Check your format setting:
+
+```bash
+echo $TERMINAL_TITLE_FORMAT
+```
+
+### Terminal-Specific Configuration
+
+Some terminals require additional settings:
+
+**tmux** (`~/.tmux.conf`):
+
+```bash
+set -g set-titles on
+set -g set-titles-string "#T"
+```
+
+**screen** (`~/.screenrc`):
+
+```bash
+termcapinfo xterm* ti@:te@
+```
+
+**VS Code**: Enable "Terminal > Integrated: Allow Workspace Shell"
+
+## Related
+
+- `workflows/git-workflow.md` - Git workflow with branch naming
+- `workflows/branch.md` - Branch creation and lifecycle
+- `tools/opencode/opencode.md` - OpenCode session management