Add adaptive review workflow and XML naming standards

.claude/commands/autotask.md

@@ -0,0 +1,106 @@
+---
+description: Execute complete development task autonomously from description to PR-ready state
+---
+
+# /autotask - Autonomous Task Execution
+
+Execute a complete development task autonomously from description to PR-ready state.
+
+## Usage
+
+```
+/autotask "task description"
+```
+
+## What This Command Does
+
+Takes your task description and autonomously delivers a pull request ready for your review. The command analyzes task complexity, sets up an isolated worktree environment, implements the solution using appropriate agents, performs adaptive validation scaled to risk level, and handles bot feedback intelligently.
+
+You only need to provide the task description and review the final PR.
+
+## Execution Flow
+
+Read @rules/git-worktree-task.mdc for comprehensive autonomous workflow guidance.
+
+<task-preparation>
+Ensure you have clear, unambiguous requirements before starting implementation. If the task description is unclear or has multiple valid interpretations, use @commands/create-prompt.md to ask clarifying questions and create a structured prompt. For tasks with clear requirements and single valid interpretation, proceed directly to implementation.
+</task-preparation>
+
+<worktree-setup>
+Create a fully functional, isolated development environment in .gitworktrees/ where all tests pass and the project is ready for development work. Ensure the environment is secure (prevent shell injection), handle any conflicts, and set up all necessary dependencies and configurations using /setup-environment.
+</worktree-setup>
+
+<autonomous-execution>
+Implement the solution following project patterns and standards. Build a plan for which agents or approaches to use based on the task type. Available specialized agents:
+
+- Dixon (.claude/agents/dev-agents/debugger.md): Root cause analysis, reproduces issues, identifies underlying problems
+- Ada (.claude/agents/dev-agents/autonomous-developer.md): Implementation work, writes tests
+- Phil (.claude/agents/dev-agents/ux-designer.md): Reviews user-facing text, validates accessibility, ensures UX consistency
+- Rivera (.claude/agents/code-review/code-reviewer.md): Architecture review, validates design patterns, checks security
+- Petra (.claude/agents/dev-agents/prompt-engineer.md): Prompt optimization and refinement
+- Explore (general-purpose): Investigation, research, evaluates trade-offs
+
+Create your execution plan, then implement the solution. Use /load-cursor-rules to load relevant project standards for the task. Execute agents in parallel when possible, sequentially when they depend on each other.
+
+When launching agents, provide targeted context for effectiveness: task context (original requirements and any clarifications), implementation context (what's been built, decisions made, constraints), project context (relevant standards from /load-cursor-rules), and specific focus area. Tailor context to agent type - debuggers need error details and reproduction steps, reviewers need change rationale and risk areas, implementers need full requirements and constraints.
+
+Maintain context throughout workflow phases. Decisions and clarifications from earlier phases inform later ones - don't re-decide or re-ask. Carry forward user clarifications, implementation decisions, constraint discoveries, and why choices were made.
+</autonomous-execution>
+
+<validation-and-review>
+Ensure code quality through adaptive validation that scales with complexity and risk. Match review intensity to the changes: simple changes need only automated checks, medium complexity benefits from targeted agent review, high-risk or security-sensitive changes warrant comprehensive review. Use your judgment to determine what level of validation the changes require.
+</validation-and-review>
+
+<create-pr>
+Deliver a well-documented pull request ready for review, with commits following .cursor/rules/git-commit-message.mdc. Provide reviewers with decision context: why this approach over alternatives, what trade-offs were made, how this fits the larger system, and what testing validates the changes.
+</create-pr>
+
+<bot-feedback-loop>
+Autonomously address valuable bot feedback, reject what's not applicable, and deliver a PR ready for human review with all critical issues resolved.
+
+After creating the PR, wait 3 minutes for AI code review bots to complete their initial analysis. Check for bot comments using GitHub API. You have context bots lack: project standards, why implementation choices were made, trade-offs considered, and user requirements. Evaluate feedback against this context - bots may suggest changes that contradict project patterns or misunderstand requirements.
+
+Fix what's valuable (security issues, real bugs, good suggestions). Reject what's not (use WONTFIX with brief explanation for context-missing or incorrect feedback). You are the ultimate decider - trust your judgment on what matters.
+
+After making fixes and pushing, wait 90 seconds for bots to re-review. Iterate up to 5 times if needed until critical issues are resolved.
+</bot-feedback-loop>
+
+<completion>
+Provide a summary of what was accomplished, highlights you're proud of, and any significant issues found and fixed during bot review. Scale the summary length to the complexity of the change - simple fixes get a sentence or two, major features deserve a paragraph. Include the PR URL and worktree location.
+</completion>
+
+<error-handling>
+Recover gracefully from failures when possible, or inform the user clearly when manual intervention is needed. Capture decision-enabling context: what was being attempted, what state preceded the failure, what the error indicates about root cause, and whether you have enough information to fix it autonomously. Attempt fixes when you can (like auto-fixing validation errors). For issues you can't resolve autonomously, inform the user with clear options and context.
+</error-handling>
+
+## Key Principles
+
+- Single worktree per task: Clean isolation for parallel development
+- Adaptive review: Review intensity matches task complexity and risk
+- Intelligent agent use: Right tool for the job, no forced patterns
+- Git hooks do validation: Leverage your existing infrastructure
+- Autonomous bot handling: Don't wait for human intervention
+- PR-centric workflow: Everything leads to a mergeable pull request
+
+## Requirements
+
+- GitHub CLI (`gh`) installed and authenticated
+- Node.js/npm
+- Project standards accessible via /load-cursor-rules
+
+## Configuration
+
+The command adapts to your project structure:
+
+- Detects git hooks (husky, pre-commit)
+- Detects test runners (jest, mocha, vitest, etc.)
+- Finds linting configs (eslint, prettier, etc.)
+- Uses available build scripts
+- Respects project-specific conventions
+
+## Notes
+
+- This command creates real commits and PRs
+- All work happens in isolated worktrees
+- Bot feedback handling is autonomous but intelligent
+- Worktrees are preserved until you explicitly remove them

.claude/commands/handoff-context.md

@@ -55,12 +55,15 @@ numbers] </work_completed>
 
 **DO NOT ASK** - Just do it:
 
-1. Generate a unique filename: `/tmp/context_handoff_TIMESTAMP.md` where TIMESTAMP is the current Unix timestamp
+1. Generate a unique filename: `/tmp/context_handoff_TIMESTAMP.md` where TIMESTAMP is
+   the current Unix timestamp
 2. Use **Write tool** to save the handoff content to that unique filename
-3. Use **Bash** to copy the file you just created: `pbcopy < /tmp/context_handoff_TIMESTAMP.md`
+3. Use **Bash** to copy the file you just created:
+   `pbcopy < /tmp/context_handoff_TIMESTAMP.md`
 4. Confirm: `📋 Copied to clipboard`
 
-**Implementation:** First run `date +%s` to get the timestamp, then use that value in both the Write and Bash commands.
+**Implementation:** First run `date +%s` to get the timestamp, then use that value in
+both the Write and Bash commands.
 
 **Why Write tool instead of heredoc?**
 

.claude/commands/setup-environment.md

@@ -2,22 +2,234 @@
 description: Initialize development environment for git worktree
 ---
 
-Make this worktree a fully functional development environment where all tests pass.
+# Setup Development Environment
 
-You're in a fresh git worktree. Your job is to get it into the same working state as the
-main development directory. After you finish, running the full validation suite should
-pass - type checking, linting, unit tests, and integration tests.
+Initialize a git worktree as a fully functional development environment with all
+dependencies, configurations, and validation tools.
 
-To do this, you'll need to:
+## What This Command Does
 
-- Install whatever dependencies this project needs
-- Run any code generation or build steps required
-- Copy environment configuration from the parent directory so integration tests can
-  connect to databases and services
+You're in a fresh git worktree. This command will:
 
-Look at what kind of project this is and make intelligent decisions about what needs to
-happen. If something fails or seems unusual, investigate and adapt. Report what you're
-doing as you go so the user understands the progress.
+1. Install all project dependencies
+2. Copy necessary environment configurations
+3. Set up git hooks (husky/pre-commit)
+4. Run any required build/generation steps
+5. Verify everything works correctly
 
-The success criteria: after you're done, `pnpm pre-push` (or equivalent validation)
-passes completely. No failing tests, no type errors, no missing dependencies.
+## Detection Phase
+
+First, I'll analyze the project structure to understand what needs to be set up:
+
+<detect-project-type>
+Checking for project indicators:
+- package.json → Node.js/JavaScript/TypeScript project
+- requirements.txt/Pipfile → Python project
+- Gemfile → Ruby project
+- go.mod → Go project
+- Cargo.toml → Rust project
+- pom.xml/build.gradle → Java project
+- .csproj → .NET project
+</detect-project-type>
+
+<detect-package-manager>
+For Node.js projects, detecting package manager:
+- pnpm-lock.yaml → pnpm
+- yarn.lock → yarn
+- package-lock.json → npm
+- bun.lockb → bun
+</detect-package-manager>
+
+## Setup Steps
+
+### 1. Install Dependencies
+
+```bash
+# Based on detected package manager
+echo "📦 Installing dependencies..."
+
+# Node.js
+if [ -f "package.json" ]; then
+  if [ -f "pnpm-lock.yaml" ]; then
+    pnpm install
+  elif [ -f "yarn.lock" ]; then
+    yarn install
+  elif [ -f "bun.lockb" ]; then
+    bun install
+  else
+    npm install
+  fi
+fi
+
+# Python
+if [ -f "requirements.txt" ]; then
+  pip install -r requirements.txt
+elif [ -f "Pipfile" ]; then
+  pipenv install
+fi
+
+# Add other language-specific installations as needed
+```
+
+### 2. Copy Environment Configuration
+
+```bash
+echo "🔐 Setting up environment configuration..."
+
+# Get the main working directory (parent of .gitworktrees)
+MAIN_DIR=$(git worktree list --porcelain | grep "^worktree" | head -1 | cut -d' ' -f2)
+
+# Copy environment files if they exist
+ENV_FILES=(.env .env.local .env.development .env.test)
+for env_file in "${ENV_FILES[@]}"; do
+  if [ -f "$MAIN_DIR/$env_file" ]; then
+    echo "  Copying $env_file from main directory..."
+    cp "$MAIN_DIR/$env_file" "./$env_file"
+  fi
+done
+
+# Copy any other config files that aren't in version control
+CONFIG_FILES=(.secrets.json local.config.js config.local.json)
+for config_file in "${CONFIG_FILES[@]}"; do
+  if [ -f "$MAIN_DIR/$config_file" ]; then
+    echo "  Copying $config_file from main directory..."
+    cp "$MAIN_DIR/$config_file" "./$config_file"
+  fi
+done
+```
+
+### 3. Setup Git Hooks
+
+```bash
+echo "🪝 Setting up git hooks..."
+
+# Get the main working directory
+MAIN_DIR=$(git worktree list --porcelain | grep "^worktree" | head -1 | cut -d' ' -f2)
+
+# Husky (most common in JS/TS projects)
+if [ -d "$MAIN_DIR/.husky" ] || [ -d ".husky" ]; then
+  echo "  Installing Husky hooks..."
+  npx husky install
+  echo "  ✓ Husky hooks installed"
+fi
+
+# Pre-commit (Python and multi-language projects)
+if [ -f "$MAIN_DIR/.pre-commit-config.yaml" ] || [ -f ".pre-commit-config.yaml" ]; then
+  echo "  Installing pre-commit hooks..."
+  if command -v pre-commit >/dev/null 2>&1; then
+    pre-commit install
+    echo "  ✓ Pre-commit hooks installed"
+  else
+    echo "  ⚠️ pre-commit not installed, run: pip install pre-commit"
+  fi
+fi
+
+# Simple git hooks (legacy projects)
+if [ -d "$MAIN_DIR/.git/hooks" ]; then
+  # Check for custom hooks that need copying
+  for hook in pre-commit pre-push commit-msg; do
+    if [ -f "$MAIN_DIR/.git/hooks/$hook" ] && [ ! -f ".git/hooks/$hook" ]; then
+      echo "  Copying $hook hook..."
+      cp "$MAIN_DIR/.git/hooks/$hook" ".git/hooks/$hook"
+      chmod +x ".git/hooks/$hook"
+    fi
+  done
+fi
+
+echo "  ✓ Git hooks configured for this worktree"
+```
+
+### 4. Run Build/Generation Steps
+
+```bash
+echo "🏗️ Running build and generation steps..."
+
+# Check for code generation needs
+if [ -f "package.json" ]; then
+  # Prisma generation
+  if grep -q "@prisma/client" package.json; then
+    echo "  Generating Prisma client..."
+    npx prisma generate
+  fi
+
+  # GraphQL codegen
+  if [ -f "codegen.yml" ] || [ -f "codegen.ts" ]; then
+    echo "  Running GraphQL codegen..."
+    npm run codegen || yarn codegen || npx graphql-codegen
+  fi
+
+  # Build if needed for development
+  if grep -q '"prepare"' package.json; then
+    echo "  Running prepare script..."
+    npm run prepare || yarn prepare
+  fi
+
+  # TypeScript declarations
+  if [ -f "tsconfig.json" ] && grep -q '"declaration"' tsconfig.json; then
+    echo "  Building TypeScript declarations..."
+    npx tsc --emitDeclarationOnly || true
+  fi
+fi
+```
+
+### 5. Verify Setup
+
+```bash
+echo "🔍 Verifying environment setup..."
+
+# Run git hooks to verify everything works
+echo "Testing git hooks..."
+if [ -d ".husky" ]; then
+  echo "  Running Husky pre-commit hooks..."
+  npx husky run pre-commit && echo "  ✓ Husky hooks working" || echo "  ⚠️ Some checks failed (fixing...)"
+elif [ -f ".pre-commit-config.yaml" ]; then
+  echo "  Running pre-commit hooks..."
+  pre-commit run --all-files && echo "  ✓ Pre-commit hooks working" || echo "  ⚠️ Some checks failed (fixing...)"
+else
+  echo "  ⚠️ No git hooks configured - consider adding husky or pre-commit"
+fi
+
+# Quick sanity checks
+if [ -f "package.json" ]; then
+  echo "Testing build..."
+  npm run build 2>/dev/null || yarn build 2>/dev/null || echo "  ⚠️ No build script"
+fi
+
+# Check environment files
+if [ -f ".env" ]; then
+  echo "✅ Environment configuration present"
+fi
+
+echo ""
+echo "✅ Environment setup complete!"
+echo ""
+echo "This worktree is now ready for development:"
+echo "  - All dependencies installed"
+echo "  - Environment configured"
+echo "  - Git hooks installed and working"
+echo "  - Ready for development"
+echo ""
+echo "Your git hooks will handle all validation when you commit."
+```
+
+## Error Handling
+
+If any step fails, I'll:
+
+1. Identify what went wrong
+2. Attempt to fix common issues automatically
+3. Provide clear guidance on manual fixes if needed
+4. Continue with other steps when safe to do so
+
+## Success Criteria
+
+After setup completes:
+
+- All dependencies are installed
+- Environment variables are configured
+- Git hooks are properly installed and working
+- The worktree is ready for development
+
+The goal is a worktree that's immediately productive - no missing dependencies, no
+failing tests, no configuration issues. Your existing git hooks (husky/pre-commit)
+handle all validation automatically when you commit.

.cursor/commands/autotask.md

@@ -0,0 +1 @@
+../../.claude/commands/autotask.md

.cursor/rules/prompt-engineering.mdc

@@ -317,6 +317,10 @@ const auth = new OAuth2Client(clientId, clientSecret);
 
 Guidelines for XML structure:
 
+- **Use semantic names, not numbers**: `<task-preparation>` not `<phase-1>`, `<create-pr>` not `<step-6>`
+  - Numbered tags are brittle: reordering requires renumbering all tags and references
+  - Semantic tags are self-documenting: `<validation-and-review>` tells you what it does
+  - Example: A workflow with `<task-preparation>`, `<execution>`, `<review>` stays clear even when phases are added or reordered
 - Be consistent with tag names throughout your codebase (always use `<task>` not
   sometimes `<objective>`)
 - Use semantically meaningful tag names that describe the content