diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index 8c490ea928..6a7b30b957 100644 --- a/.agent/AGENTS.md +++ b/.agent/AGENTS.md @@ -63,9 +63,15 @@ Detection keywords: - Parallel sessions inheriting wrong branch state - "Your local changes would be overwritten" errors -**When option 3 is acceptable**: Documentation-only changes (README, CHANGELOG, docs/), typo fixes, version bumps via release script. +**When option 3 is acceptable**: Documentation-only changes (README, CHANGELOG, docs/), typo fixes, version bumps via release script, **planning files (TODO.md, todo/)**. **When option 3 is NOT acceptable**: Any code changes, configuration files, scripts. +**Planning files exception**: TODO.md and todo/ can be edited directly on main and auto-committed: +```bash +~/.aidevops/agents/scripts/planning-commit-helper.sh "plan: add new task" +``` +Planning files are metadata about work, not the work itself - they don't need PR review. + 4. Create worktree: `~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{name}` 5. After creating branch, call `session-rename_sync_branch` tool diff --git a/.agent/plan-plus.md b/.agent/plan-plus.md index af597e9159..1c5df2897c 100644 --- a/.agent/plan-plus.md +++ b/.agent/plan-plus.md @@ -101,6 +101,31 @@ Plan+ can write directly to planning files: **Use this for:** Capturing tasks, writing plans, documenting decisions. +## Auto-Commit Planning Files + +After modifying TODO.md or todo/, commit and push immediately: + +```bash +~/.aidevops/agents/scripts/planning-commit-helper.sh "plan: {description}" +``` + +**When to auto-commit:** +- After adding a new task +- After updating task status +- After writing or updating a plan + +**Commit message conventions:** + +| Action | Message | +|--------|---------| +| New task | `plan: add {task title}` | +| Status update | `plan: {task} → done` | +| New plan | `plan: add {plan name}` | +| Batch updates | `plan: batch planning updates` | + +**Why this bypasses branch/PR workflow:** Planning files are metadata about work, +not the work itself. They don't need code review - just quick persistence. + ## Handoff to Build+ (IMPORTANT) **When all planning decisions are made and you're ready to implement code:** diff --git a/.agent/scripts/planning-commit-helper.sh b/.agent/scripts/planning-commit-helper.sh new file mode 100755 index 0000000000..2f2eec4bf4 --- /dev/null +++ b/.agent/scripts/planning-commit-helper.sh @@ -0,0 +1,209 @@ +#!/bin/bash +# shellcheck disable=SC2310 +# ============================================================================= +# Planning File Auto-Commit Helper +# ============================================================================= +# Commits and pushes changes to TODO.md and todo/ without branch ceremony. +# Called automatically by Plan+ agent after planning file modifications. +# +# Usage: +# planning-commit-helper.sh "plan: add new task" +# planning-commit-helper.sh --check # Just check if changes exist +# planning-commit-helper.sh --status # Show planning file status +# +# Exit codes: +# 0 - Success (or no changes to commit) +# 1 - Error (not in git repo, etc.) +# ============================================================================= + +set -euo pipefail + +# Colors +readonly RED='\033[0;31m' +readonly GREEN='\033[0;32m' +readonly YELLOW='\033[1;33m' +readonly BLUE='\033[0;34m' +readonly NC='\033[0m' + +# Planning file patterns +readonly PLANNING_PATTERNS="^TODO\.md$|^todo/" + +log_info() { + echo -e "${BLUE}[plan]${NC} $1" +} + +log_success() { + echo -e "${GREEN}[plan]${NC} $1" +} + +log_warning() { + echo -e "${YELLOW}[plan]${NC} $1" +} + +log_error() { + echo -e "${RED}[plan]${NC} $1" >&2 +} + +# Check if we're in a git repository +check_git_repo() { + if ! git rev-parse --is-inside-work-tree &>/dev/null; then + log_error "Not in a git repository" + return 1 + fi + return 0 +} + +# Check if there are planning file changes +has_planning_changes() { + # Check both staged and unstaged changes + if git diff --name-only HEAD 2>/dev/null | grep -qE "$PLANNING_PATTERNS"; then + return 0 + fi + if git diff --name-only --cached 2>/dev/null | grep -qE "$PLANNING_PATTERNS"; then + return 0 + fi + # Also check untracked files in todo/ + if git ls-files --others --exclude-standard 2>/dev/null | grep -qE "$PLANNING_PATTERNS"; then + return 0 + fi + return 1 +} + +# List planning file changes +list_planning_changes() { + local changes="" + + # Staged changes + local staged + staged=$(git diff --name-only --cached 2>/dev/null | grep -E "$PLANNING_PATTERNS" || true) + + # Unstaged changes + local unstaged + unstaged=$(git diff --name-only 2>/dev/null | grep -E "$PLANNING_PATTERNS" || true) + + # Untracked + local untracked + untracked=$(git ls-files --others --exclude-standard 2>/dev/null | grep -E "$PLANNING_PATTERNS" || true) + + # Combine unique + changes=$(echo -e "${staged}\n${unstaged}\n${untracked}" | sort -u | grep -v '^$' || true) + echo "$changes" +} + +# Show status of planning files +show_status() { + check_git_repo || return 1 + + echo "Planning file status:" + echo "=====================" + + if has_planning_changes; then + echo -e "${YELLOW}Modified planning files:${NC}" + list_planning_changes | while read -r file; do + [[ -n "$file" ]] && echo " - $file" + done + else + echo -e "${GREEN}No planning file changes${NC}" + fi + + return 0 +} + +# Main commit function +commit_planning_files() { + local commit_msg="${1:-plan: update planning files}" + + check_git_repo || return 1 + + # Check for changes + if ! has_planning_changes; then + log_info "No planning file changes to commit" + return 0 + fi + + # Show what we're committing + log_info "Planning files to commit:" + list_planning_changes | while read -r file; do + [[ -n "$file" ]] && echo " - $file" + done + + # Pull latest to avoid conflicts (rebase to keep history clean) + local current_branch + current_branch=$(git branch --show-current) + if git remote get-url origin &>/dev/null; then + log_info "Pulling latest changes..." + if ! git pull --rebase origin "$current_branch" 2>/dev/null; then + log_warning "Pull failed (may be offline or new branch)" + fi + fi + + # Stage only planning files + git add TODO.md 2>/dev/null || true + git add todo/ 2>/dev/null || true + + # Check if anything was staged + if git diff --cached --quiet 2>/dev/null; then + log_info "No changes staged after adding planning files" + return 0 + fi + + # Commit (skip hooks - planning commits don't need full linting) + log_info "Committing: $commit_msg" + if ! git commit -m "$commit_msg" --no-verify; then + log_error "Commit failed" + return 1 + fi + + # Push (silent fail if offline or no permissions) + if git remote get-url origin &>/dev/null; then + log_info "Pushing to remote..." + if git push origin HEAD 2>/dev/null; then + log_success "Planning files committed and pushed" + else + log_warning "Committed locally (push failed - will retry later)" + fi + else + log_success "Committed locally (no remote configured)" + fi + + return 0 +} + +# Main +main() { + case "${1:-}" in + --check) + check_git_repo || exit 1 + if has_planning_changes; then + echo "PLANNING_CHANGES=true" + exit 0 + else + echo "PLANNING_CHANGES=false" + exit 0 + fi + ;; + --status) + show_status + exit $? + ;; + --help|-h) + echo "Usage: planning-commit-helper.sh [OPTIONS] [COMMIT_MESSAGE]" + echo "" + echo "Options:" + echo " --check Check if planning files have changes" + echo " --status Show planning file status" + echo " --help Show this help" + echo "" + echo "Examples:" + echo " planning-commit-helper.sh 'plan: add new task'" + echo " planning-commit-helper.sh --check" + exit 0 + ;; + *) + commit_planning_files "$@" + exit $? + ;; + esac +} + +main "$@" diff --git a/.agent/scripts/pre-edit-check.sh b/.agent/scripts/pre-edit-check.sh index 6c56c63716..a223b613c1 100755 --- a/.agent/scripts/pre-edit-check.sh +++ b/.agent/scripts/pre-edit-check.sh @@ -58,7 +58,8 @@ is_docs_only() { local code_patterns="feature|fix|bug|implement|refactor|add.*function|update.*code|create.*script|modify.*config|change.*logic|new.*api|endpoint|enhance|port|ssl|helper" # Docs-only indicators (positive match) - local docs_patterns="^readme|^changelog|^documentation|docs/|typo|spelling|comment only|license only|^update readme|^update changelog|^update docs" + # Includes planning files (TODO.md, todo/) which can be edited on main + local docs_patterns="^readme|^changelog|^documentation|docs/|typo|spelling|comment only|license only|^update readme|^update changelog|^update docs|^todo|todo\.md|plans\.md|planning|^add task|^update task|backlog" # Check for code patterns first (takes precedence) if echo "$task_lower" | grep -qE "$code_patterns"; then