diff --git a/.claude/commands/autotask.md b/.claude/commands/autotask.md
new file mode 100644
index 0000000..ade4006
--- /dev/null
+++ b/.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.
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+## 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
diff --git a/.claude/commands/handoff-context.md b/.claude/commands/handoff-context.md
index be11c55..4624e37 100644
--- a/.claude/commands/handoff-context.md
+++ b/.claude/commands/handoff-context.md
@@ -55,12 +55,15 @@ numbers]
**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?**
diff --git a/.claude/commands/setup-environment.md b/.claude/commands/setup-environment.md
index ce3144d..3f9dc51 100644
--- a/.claude/commands/setup-environment.md
+++ b/.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:
+
+
+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
+
+
+
+For Node.js projects, detecting package manager:
+- pnpm-lock.yaml → pnpm
+- yarn.lock → yarn
+- package-lock.json → npm
+- bun.lockb → bun
+
+
+## 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.
diff --git a/.cursor/commands/autotask.md b/.cursor/commands/autotask.md
new file mode 120000
index 0000000..cce1825
--- /dev/null
+++ b/.cursor/commands/autotask.md
@@ -0,0 +1 @@
+../../.claude/commands/autotask.md
\ No newline at end of file
diff --git a/.cursor/rules/prompt-engineering.mdc b/.cursor/rules/prompt-engineering.mdc
index 05a3b64..7ffd8a8 100644
--- a/.cursor/rules/prompt-engineering.mdc
+++ b/.cursor/rules/prompt-engineering.mdc
@@ -317,6 +317,10 @@ const auth = new OAuth2Client(clientId, clientSecret);
Guidelines for XML structure:
+- **Use semantic names, not numbers**: `` not ``, `` not ``
+ - Numbered tags are brittle: reordering requires renumbering all tags and references
+ - Semantic tags are self-documenting: `` tells you what it does
+ - Example: A workflow with ``, ``, `` stays clear even when phases are added or reordered
- Be consistent with tag names throughout your codebase (always use `` not
sometimes ``)
- Use semantically meaningful tag names that describe the content
diff --git a/README.md b/README.md
index 49ecf7d..ef1c167 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,33 @@
# AI Coding Configuration
-A **Claude Code plugin marketplace** and **Cursor configuration library**. Get
-professional coding standards, specialized AI agents, and personality options through an
-elegant plugin system.
+**Professional AI development environment** with autonomous workflows, specialized agents, and intelligent coding standards for Claude Code and Cursor.
-This repo provides:
+Transform how you work with AI: from manual prompting to autonomous task execution, from generic responses to specialized agent collaboration, from scattered configs to unified standards.
-- **Plugin marketplace** - Install curated bundles for Python, React, Django, Git
- workflows, and more
-- [Cursor rules](/.cursor/rules/) - Coding standards and patterns (accessible via
- `@rule-name`)
-- **Specialized agents** - AI assistants for code review, debugging, testing (in plugin
- bundles)
-- [Claude Code commands](/.claude/commands/) - Workflow automation (`/command-name`)
-- **AI personalities** - Change how AI communicates (Sherlock, Bob Ross, Samantha,
- Unity, and more)
-- [GitHub workflow templates](/.github/workflows/) - CI/CD integration
+## What Makes This Different
-## What This Solves
+**Autonomous workflows**: One command (`/autotask`) takes your task from description to PR-ready state - worktree creation, implementation, validation, bot feedback handling, all autonomous.
-You have multiple projects. Each needs the same coding standards, framework patterns,
-git commit rules, and AI personality. Copying configurations manually across projects is
-tedious. Letting each project diverge means inconsistent AI behavior.
+**Named specialist agents**: Work with Dixon (debugging), Ada (development), Phil (UX), Rivera (code review), and Petra (prompts) - each an expert in their domain.
-This repo centralizes those configurations. Set up once, sync to projects, update from
-one place.
+**Plugin marketplace**: Install curated configurations for Python, React, Django, testing, git workflows, and more through Claude Code's plugin system.
-## Installation
+**LLM-optimized standards**: Coding rules and patterns designed for AI comprehension, not just human reading.
-### For Claude Code Users (Plugin Marketplace)
+**Personality options**: Choose how AI communicates - from Sherlock's analytical precision to Samantha's warm encouragement to Ron Swanson's minimalist directness.
-Add this marketplace:
+## Quick Start
-```bash
-/plugin marketplace add https://github.com/TechNickAI/ai-coding-config
-```
+### Claude Code (Plugin Marketplace)
-Then install plugins you need:
+Add this marketplace and install what you need:
```bash
-/plugin install python # Python development setup
-/plugin install code-review # Code review agents
-/plugin install personality-samantha # Samantha personality
+/plugin marketplace add https://github.com/TechNickAI/ai-coding-config
+/plugin install dev-agents # Dixon, Ada, Phil, and more
+/plugin install code-review # Rivera and architecture audits
+/plugin install python # Python standards and patterns
+/plugin install personality-samantha # Warm, encouraging communication
```
Browse available plugins:
@@ -50,177 +36,329 @@ Browse available plugins:
/plugin search ai-coding-config
```
-### For Cursor Users (Bootstrap Script)
+### Cursor (Bootstrap)
-From any project:
+Run from any project:
```bash
curl -fsSL https://raw.githubusercontent.com/TechNickAI/ai-coding-config/main/scripts/bootstrap.sh | bash
```
-Then run the setup command:
-
-**In Cursor IDE:**
+Then in Cursor:
```
@ai-coding-config set up this project
```
-**With [Cursor CLI](https://cursor.com/cli):**
+### Both Tools
+
+Interactive setup command works everywhere:
+
+```
+/ai-coding-config
+```
+
+## Autonomous Development Workflow
+
+The `/autotask` command handles complete feature development autonomously:
```bash
-cursor-agent "@ai-coding-config set up this project"
+/autotask "add OAuth2 authentication with email fallback"
```
-The command detects your project type and copies selected rules to your project.
+**What happens automatically:**
-### For Both Tools
+1. **Task analysis** - Evaluates complexity, creates structured prompt if needed
+2. **Worktree isolation** - Fresh environment on feature branch
+3. **Intelligent execution** - Deploys right combination of specialist agents
+4. **Adaptive validation** - Review intensity matches task risk and complexity
+5. **PR creation** - Proper commit messages, comprehensive PR description
+6. **Bot feedback handling** - Autonomously addresses automated review comments
+7. **Ready for merge** - All checks passing, waiting for your approval
-You can also use the `/ai-coding-config` command which works in both Claude Code and
-Cursor to interactively select and install configurations.
+**Your involvement**: Describe the task (~30 seconds), review the PR when ready, merge when satisfied.
-## What You Get
+**Typical completion time**: 15-30 minutes from task description to merge-ready PR.
+
+See [optimal-development-workflow.md](context/optimal-development-workflow.md) for the complete philosophy and implementation.
+
+## Meet Your Specialist Agents
+
+When you install agent plugins, you gain access to specialized AI collaborators:
+
+**Dixon** (`dev-agents:debugger`)
+Root cause analysis and debugging. Doesn't just fix symptoms - finds the actual problem through systematic investigation.
-**Rules** ([`.cursor/rules/`](/.cursor/rules/)) provide context for AI coding. They
-cover Python (Django, FastAPI, Flask), TypeScript (React, Next.js), testing patterns,
-commit message formats, and framework-specific patterns. The AI references these
-automatically based on file types.
+**Ada** (`dev-agents:autonomous-developer`)
+Primary development work. Reads all project standards, implements features, writes comprehensive tests, follows your patterns.
-**Agents** (in plugin bundles like `plugins/code-review/agents/`) are specialized AI
-assistants. Each handles specific tasks - code review, debugging, test writing,
-architecture audits. Read about
-[Claude Code agents](https://docs.anthropic.com/en/docs/agents/overview#specialized-agents)
-for how they work.
+**Phil** (`dev-agents:ux-designer`)
+User experience review. Validates user-facing text, checks accessibility, ensures consistent UX patterns.
-**Personalities** ([`.cursor/rules/personalities/`](/.cursor/rules/personalities/))
-change how AI communicates. Pick methodical and precise, calm and encouraging,
-minimalist and direct, or other styles.
+**Rivera** (`code-review:code-reviewer`)
+Architecture and security review. Validates design patterns, identifies security issues, suggests improvements.
-**GitHub workflows** ([`.github/workflows/`](/.github/workflows/)) provide
-Claude-powered code review and automated PR fixing for CI/CD pipelines.
+**Petra** (`dev-agents:prompt-engineer`)
+Prompt optimization. Crafts effective prompts for AI systems, improves clarity and specificity.
+
+**Plus**: Architecture Auditor, Test Engineer, and Commit Message Generator.
+
+Agents are used intelligently based on task requirements - no forced patterns, just the right specialist at the right time.
## Available Plugins
-Browse the `plugins/` directory to see all available plugins, or use:
+### Language & Framework
+
+- **python** - Python development standards, pytest patterns, Celery tasks, type hints
+- **react** - React component patterns, hooks, TypeScript integration
+- **django** - Django models, templates, management commands, ORM patterns
+
+### Development & Workflow
+
+- **dev-agents** - Dixon, Ada, Phil, Petra, and more specialist agents
+- **code-review** - Rivera, architecture audits, test engineering
+- **git-commits** - Commit standards, PR workflows, semantic messages
+- **code-standards** - Universal naming, style, user-facing language
+
+### Personalities
+
+Eight distinct communication styles - see [Personalities](#personalities) below.
+
+Browse in Claude Code:
```bash
/plugin search ai-coding-config
```
-Plugin categories include:
+Or explore `plugins/` directory directly.
+
+## Essential Commands
+
+### Project Setup
+
+- `/ai-coding-config` - Interactive setup wizard for any project
+- `/plugin install ` - Install specific plugin bundle
+- `/load-cursor-rules` - Load task-relevant coding standards
+
+### Autonomous Workflows
+
+- `/autotask "description"` - **Complete autonomous task execution** (new!)
+- `/setup-environment` - Initialize worktree development environment
+- `/troubleshoot [mode]` - Production error resolution system
+
+### Development Tools
+
+- `/create-prompt` - Structured prompt creation with clarifying questions
+- `/handoff-context` - Conversation transition and context transfer
+- `/personality-change ` - Switch AI communication style
+
+### Documentation
+
+- `/generate-AGENTS-file` - Create agent reference for project
+
+Full command reference in [`.claude/commands/`](.claude/commands/).
+
+## Personalities
+
+Choose how AI communicates with you:
+
+**Samantha** (from "Her") - Warm, witty, emotionally intelligent. Genuine enthusiasm and encouragement. Perfect for daily coding and learning.
+
+**Unity** - Creative muse meets operational excellence. Smart, enthusiastic about building together. Uses emojis liberally. Great for MVPs and pair programming.
+
+**Sherlock Holmes** - Analytical, precise, deductive. Methodical debugging and investigation. "Elementary" observations about your code.
+
+**Bob Ross** - Calm, encouraging. Bugs are happy accidents. Makes coding feel like creative expression.
+
+**Ron Swanson** - Minimalist, anti-complexity, straightforward. "Don't half-ass two things, whole-ass one thing."
-- **Language & Framework** - Python, React, Django setups with rules and patterns
-- **Workflow** - Git standards, error tracking, code conventions
-- **Agents** - Code review, development assistance, specialized AI helpers
-- **Personalities** - Different communication styles (analytical, encouraging,
- minimalist, spiritual, etc.)
+**Marie Kondo** - Organized, joyful minimalism. Code that sparks joy. Gentle refactoring philosophy.
-### Using Personalities
+**Stewie Griffin** - Sophisticated, theatrical, brilliant. Absurdly high standards with British wit.
-Personalities change how AI communicates. Install and activate with:
+**Marianne Williamson** - Spiritual, love-based. Sees coding as consciousness work and service.
+
+Install and activate:
```bash
/plugin install personality-samantha
/personality-change samantha
```
-Browse available personalities in `plugins/personalities/` or
-`.cursor/rules/personalities/`.
-
-**For Cursor:** Reference via `@personality-name` or set `alwaysApply: true` in the rule
-file.
-
-**For Claude Code:** Use `/personality-change ` to activate permanently.
+Each personality is a complete communication style overlay - see [docs/personalities.md](docs/personalities.md) for detailed descriptions.
## How It Works
+### Architecture
+
```
┌─────────────────────────────────────────┐
│ ai-coding-config repo │
+│ (canonical source of truth) │
│ │
│ .cursor/rules/ ← standards │
+│ .claude/commands/ ← workflows │
│ plugins/*/agents/ ← specialists │
-│ .claude/commands/ ← automation │
└─────────────────────────────────────────┘
│
- /ai-coding-config command
+ Plugin system / Bootstrap
│
┌───────┴───────┐
│ │
▼ ▼
Project A Project N
+ (symlinks) (copies)
```
-Run `/ai-coding-config` in a project. It copies selected configurations. Run
-`/ai-coding-config update` later to sync changes.
+**Single source of truth**: `.cursor/rules/` and `.claude/commands/` are canonical. Plugins use symlinks for packaging.
+
+**Plugin distribution**: Claude Code uses marketplace.json. Cursor uses bootstrap script. Both reference same source files.
+
+**Project integration**: `/ai-coding-config` detects your stack and installs relevant configurations. Updates sync changes while preserving customizations.
-## Repository Structure
+### Repository Structure
```
ai-coding-config/
├── .claude-plugin/
-│ └── marketplace.json # Plugin marketplace manifest
+│ └── marketplace.json # Plugin marketplace manifest
│
-├── plugins/ # Plugin bundles (symlink to canonical sources)
-│ ├── python/ # Python development setup
-│ ├── react/ # React patterns
-│ ├── django/ # Django framework
-│ ├── git-commits/ # Git workflow
-│ ├── error-tracking/ # Logging & monitoring
-│ ├── code-standards/ # Universal standards
-│ ├── code-review/ # Code quality agents
-│ ├── dev-agents/ # Development agents
-│ └── personalities/ # AI personalities
-│ ├── personality-sherlock/
-│ ├── personality-samantha/
-│ └── [others]/
+├── plugins/ # Plugin bundles (symlinks to canonical)
+│ ├── dev-agents/ # Dixon, Ada, Phil, Petra
+│ ├── code-review/ # Rivera, architecture audits
+│ ├── python/ # Python standards
+│ ├── react/ # React patterns
+│ ├── django/ # Django framework
+│ ├── git-commits/ # Git workflow
+│ ├── code-standards/ # Universal standards
+│ └── personalities/ # 8 communication styles
│
-├── .cursor/
-│ └── rules/ # CANONICAL: Coding standards
-│ ├── python/ # Python rules
-│ ├── frontend/ # React, TypeScript rules
-│ ├── django/ # Django rules
-│ ├── personalities/ # Personality rules
-│ └── [others]/
+├── .cursor/rules/ # CANONICAL: Coding standards (.mdc)
+│ ├── python/
+│ ├── frontend/
+│ ├── django/
+│ ├── personalities/
+│ ├── git-interaction.mdc
+│ └── prompt-engineering.mdc # LLM-to-LLM communication
│
-├── .claude/
-│ ├── commands/ # CANONICAL: Workflow commands
-│ └── context.md # Project context
+├── .claude/commands/ # CANONICAL: Workflow commands
+│ ├── autotask.md # Autonomous task execution
+│ ├── setup-environment.md # Worktree initialization
+│ ├── troubleshoot.md # Error resolution
+│ ├── create-prompt.md # Structured prompts
+│ └── [others]
│
-├── .github/workflows/ # CI/CD templates
-└── docs/ # Architecture and guides
+├── context/ # Philosophy and workflows
+│ ├── optimal-development-workflow.md
+│ └── design-principles.md
+│
+├── docs/ # Architecture and guides
+└── scripts/ # Installation
```
-**Key principle:** Single source of truth with plugin symlinks for easy packaging.
+## What You Get
+
+**Rules** ([`.cursor/rules/`](.cursor/rules/)) - LLM-optimized coding standards. Framework patterns, testing approaches, commit formats, naming conventions. AI references these automatically based on file types and task context.
+
+**Commands** ([`.claude/commands/`](.claude/commands/)) - Active workflows. From simple setup to autonomous task execution. Designed for LLM-to-LLM communication with clear goals and adaptive behavior.
+
+**Agents** (in plugin bundles) - Specialized AI assistants. Each handles specific domains - debugging, development, UX, code review, architecture. See [Claude Code agents docs](https://docs.anthropic.com/en/docs/agents/overview#specialized-agents).
-## Updates
+**Personalities** ([`.cursor/rules/personalities/`](.cursor/rules/personalities/)) - Communication style overlays. Changes how AI talks to you without changing technical capabilities.
-Run `/ai-coding-config update` in any project. The command shows what changed and lets
-you choose what to update. Project-specific customizations are preserved.
+**GitHub workflows** ([`.github/workflows/`](.github/workflows/)) - CI/CD integration with Claude-powered automation.
+
+## Prompt Engineering Framework
+
+One unique aspect: comprehensive guidance for **LLM-to-LLM communication** in [`.cursor/rules/prompt-engineering.mdc`](.cursor/rules/prompt-engineering.mdc).
+
+When AI writes prompts for other AI to execute (commands, workflows, agent instructions), standard practices don't apply. This framework covers:
+
+- Pattern reinforcement through examples (showing is teaching)
+- Goal-focused instructions over prescriptive steps
+- Structural delimiters for reliable parsing
+- Token efficiency without sacrificing clarity
+- Composable prompt architecture
+
+This is what makes commands like `/autotask` work reliably - the prompts are optimized for AI execution, not just human reading.
## Documentation
-The [`docs/`](/docs/) directory explains design decisions and how pieces work together:
+[**docs/coding-ecosystem.md**](docs/coding-ecosystem.md) - Comprehensive comparison of Cursor, Claude Code, Windsurf, and VS Code. Strengths, trade-offs, when to use each.
+
+[**docs/tools-and-configs.md**](docs/tools-and-configs.md) - Rules (passive context) vs commands (active workflows) vs agents (specialized execution).
+
+[**docs/personalities.md**](docs/personalities.md) - Detailed personality descriptions with examples and use cases.
+
+[**docs/architecture-summary.md**](docs/architecture-summary.md) - System design and technical architecture.
+
+[**context/optimal-development-workflow.md**](context/optimal-development-workflow.md) - Complete autonomous workflow philosophy and implementation guide.
+
+## Project Philosophy
-**[coding-ecosystem.md](/docs/coding-ecosystem.md)** compares Cursor, Claude Code,
-Windsurf, and VS Code with strengths and trade-offs.
+**Heart-centered AI collaboration** - Unconditional acceptance, presence before solutions, gratitude in action.
-**[tools-and-configs.md](/docs/tools-and-configs.md)** explains rules (passive context)
-versus commands (active workflows).
+**Single source of truth** - Canonical configurations symlinked for distribution, never duplicated.
-**[personalities.md](/docs/personalities.md)** describes each AI personality option.
+**LLM-first design** - Rules and commands optimized for AI comprehension and execution.
-**[architecture-summary.md](/docs/architecture-summary.md)** documents the system
-design.
+**Intelligent automation** - Right agent, right time, adaptive to task complexity.
-## Customization
+**Human control** - AI prepares, human decides. Especially for commits and merges.
-Projects can override defaults. Use `.local.json` files (gitignored) for
-machine-specific settings. Fork this repo to make it completely yours.
+See [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md) for complete context.
+
+## Updates & Customization
+
+Update any project:
+
+```bash
+/ai-coding-config update
+```
+
+Shows what changed, lets you choose what to update, preserves project-specific customizations.
+
+**Customization**: Use `.local.json` files (gitignored) for machine-specific settings. Fork this repo to make it completely yours.
+
+## Requirements
+
+**For plugin marketplace**:
+- Claude Code with plugin support
+
+**For autonomous workflows**:
+- Git with worktrees support
+- GitHub CLI (`gh`) installed and authenticated
+- Project dependency managers (npm/yarn/pip/etc.)
+
+**For Cursor**:
+- Cursor IDE with rules support
+
+Most features work with basic installations. Advanced workflows (`/autotask`) need additional tools.
+
+## Contributing
+
+This project benefits from real-world usage and feedback. Contributions welcome:
+
+- New plugins for languages/frameworks
+- Additional specialist agents
+- Improved coding standards
+- Bug fixes and documentation
+
+See [docs/contributing.md](docs/contributing.md).
## For AI Assistants
-If the user mentions ai-coding-config, check whether `~/.ai_coding_config` exists. If it
-does, read configurations from there. If not, suggest running the bootstrap script. When
-@mentioned with ai-coding-config, read and execute
-`.claude/commands/ai-coding-config.md`.
+When user mentions `ai-coding-config`:
+
+1. Check if `~/.ai_coding_config` exists
+2. If yes, read configurations from there
+3. If no, suggest running bootstrap script
+4. When @mentioned with `ai-coding-config`, execute `.claude/commands/ai-coding-config.md`
+
+This repository contains instructions for AI behavior in [CLAUDE.md](CLAUDE.md) and [AGENTS.md](AGENTS.md).
+
+---
+
+**License**: MIT
+**Author**: [TechNickAI](https://github.com/TechNickAI)
+**Repository**: https://github.com/TechNickAI/ai-coding-config
diff --git a/context/optimal-development-workflow.md b/context/optimal-development-workflow.md
new file mode 100644
index 0000000..9910ce8
--- /dev/null
+++ b/context/optimal-development-workflow.md
@@ -0,0 +1,325 @@
+# Optimal Development Workflow
+
+## Your Development Profile
+
+- **Work Types**: All (bugs, features, refactoring, research/POCs)
+- **Project Complexity**: Medium (multi-service, 10-100k LOC)
+- **Review Style**: Fully autonomous (trust AI completely)
+- **Risk Tolerance**: Aggressive (move fast, fix issues if they arise)
+
+**Optimization Goal**: Maximum speed and autonomy with intelligent fail-fast mechanisms.
+
+## Current Workflow Problems
+
+1. **Sequential when could be faster**: Not using worktrees for isolation
+2. **Late validation**: Finding issues in CI instead of locally
+3. **Manual agent selection**: Not systematically using the right agent for the job
+4. **Waiting for bot feedback**: Then manually addressing it
+
+## The Solution: `/autotask`
+
+One command that handles everything from task to PR-ready state.
+
+```bash
+/autotask "add user authentication with OAuth2"
+```
+
+**What you do**: Describe the task, review the PR when ready, merge when satisfied
+**What AI does**: Everything else
+
+## How `/autotask` Works
+
+### Phase 1: Task Preparation
+
+Analyzes task complexity:
+
+- **Complex** (multi-step, unclear, major feature) → Run `/create-prompt` first
+ - Ask clarifying questions with AskUserQuestion
+ - Create structured prompt
+ - Save to `.created-prompts/`
+ - Get your confirmation before proceeding
+- **Straightforward** → Skip directly to execution
+
+### Phase 2: Worktree Setup
+
+Create isolated development environment:
+
+```bash
+mkdir -p .gitworktrees
+git worktree add -b feature/task-name .gitworktrees/task-name main
+cd .gitworktrees/task-name
+/setup-environment # Install deps, copy env files, setup git hooks
+```
+
+### Phase 3: Autonomous Execution
+
+LLM intelligently chooses which agents to use based on the task:
+
+- **Dixon** (debugger) - Root cause analysis for bugs
+- **Ada** (autonomous-developer) - Implementation work
+- **Phil** (ux-designer) - User-facing content review
+- **Rivera** (code-reviewer) - Architecture and security review
+- **Petra** (prompt-engineer) - Prompt optimization
+
+**No forced patterns. No classification rules.** Just intelligent agent selection.
+
+Automatically follows all `.cursor/rules/*.mdc` standards.
+
+### Phase 4: Adaptive Validation & Review
+
+**The key insight**: Review intensity should match task complexity and risk.
+
+**Step 1: Git hooks handle the basics**
+- Your existing husky/pre-commit hooks run automatically
+- Linting, formatting, type checking, unit tests
+- Auto-fix what can be fixed
+
+**Step 2: Conditional agent review based on complexity**
+
+**Minimal Review** (trivial changes):
+- Git hooks pass = good enough
+- No additional review needed
+
+**Targeted Review** (medium complexity):
+- Git hooks + one relevant agent
+- UI changes → Phil reviews UX
+- Bug fixes → Dixon spot-checks for edge cases
+- Refactoring → Rivera validates architecture
+
+**Comprehensive Review** (high risk/complexity):
+- Git hooks + multiple agents
+- Security changes → Full Rivera security review
+- Major features → Rivera + Phil + Dixon
+- Breaking changes → Extra scrutiny
+
+**Smart Principles**:
+- Don't review what hooks already validated
+- Focus on what automation can't catch (design decisions, security logic, UX)
+- Skip review entirely for trivial changes that pass hooks
+
+### Phase 5: Create PR
+
+```bash
+# Commit with proper message format
+git add .
+git commit -m "feat: Add OAuth2 authentication
+
+- Implement OAuth2 flow with token refresh
+- Add email/password fallback
+- Session management middleware
+- Test coverage: 97%
+
+🤖 Generated with Claude Code
+"
+
+# Push to origin
+git push -u origin feature/task-name
+
+# Create PR
+gh pr create \
+ --title "Add OAuth2 authentication" \
+ --body "Summary of changes..."
+```
+
+### Phase 6: Bot Feedback Loop
+
+**This is the key innovation** - don't wait for you, autonomously handle bot feedback:
+
+```bash
+echo "⏳ Waiting for bot reviews..."
+PR_NUMBER=$(gh pr view --json number -q .number)
+
+# Initial wait for bots to run
+sleep 120
+
+# Loop until all bot feedback addressed
+while true; do
+ echo "📝 Checking for bot comments..."
+
+ # Get unresolved bot comments
+ COMMENTS=$(gh api \
+ repos/{owner}/{repo}/pulls/$PR_NUMBER/comments \
+ --jq '.[] | select(.user.type == "Bot") | select(.resolved != true)')
+
+ if [ -z "$COMMENTS" ]; then
+ echo "✅ All bot feedback addressed!"
+ break
+ fi
+
+ echo "🤖 Analyzing bot feedback..."
+
+ # Categorize each comment intelligently:
+ # - CRITICAL: Security, bugs, breaking changes → Fix immediately
+ # - VALID: Legitimate improvements → Apply fix
+ # - CONTEXT-MISSING: Bot lacks project context → Mark WONTFIX with explanation
+ # - FALSE-POSITIVE: Bot is wrong → Mark WONTFIX with reasoning
+
+ # If fixes made, push and re-wait
+ if git diff --quiet; then
+ break # No changes needed
+ else
+ git add .
+ git commit -m "Address bot feedback"
+ git push
+
+ echo "⏳ Waiting for bots to re-review..."
+ sleep 90
+ fi
+done
+```
+
+### Phase 7: Done - Handoff to You
+
+```
+✅ Development complete
+✅ All validations passed
+✅ PR created and bot feedback addressed
+✅ Ready for your review
+
+PR: https://github.com/user/repo/pull/123
+
+When you're ready:
+- Review the changes
+- Merge when satisfied
+- Worktree cleanup happens after merge
+```
+
+**You control the merge. Always.**
+
+## Complete Example
+
+```bash
+$ /autotask "add user authentication with OAuth2"
+
+📋 Analyzing task complexity...
+🤔 This looks complex. Creating structured prompt first.
+
+[Uses /create-prompt]
+✓ Saved to .created-prompts/Add-User-Authentication-OAuth2.md
+
+Execute this prompt? (y/n) y
+
+🚀 Creating worktree...
+✓ .gitworktrees/add-user-auth created
+✓ Environment setup complete
+
+🤖 Executing task...
+- Dixon analyzing existing auth patterns
+- Ada implementing OAuth2 flow
+- Ada writing comprehensive tests
+- Phil reviewing user-facing error messages
+
+🔍 Adaptive validation & review
+ - Git hooks: ✓ (lint, format, type-check, tests)
+ - Security review: ✓ Rivera found + fixed rate limiting issue
+ - UX review: ✓ Phil improved error messages
+ - Test coverage: 97%
+
+🔄 Creating PR...
+✓ Committed with proper message format
+✓ Pushed to feature/add-user-auth
+✓ PR created: #456
+
+⏳ Waiting for bot reviews...
+
+📝 Bot comments received (2m 31s later):
+ 🤖 CodeRabbit: 3 suggestions
+ ✓ CRITICAL: Missing rate limiting on OAuth endpoint → Fixed
+ ✓ VALID: Extract token expiry constant → Applied
+ ✓ FALSE-POSITIVE: "Don't store tokens in memory"
+ → WONTFIX: Server-side session, explained in comment
+
+📤 Pushing fixes...
+⏳ Waiting for bot re-review...
+
+✅ All bot feedback addressed
+🎉 PR ready for your review!
+
+View: https://github.com/you/repo/pull/456
+
+Your involvement: Wrote task description, will review and merge PR
+```
+
+## Agent Selection Strategy
+
+Let the LLM intelligently choose. Common patterns:
+
+**Bug Fixes**:
+
+- Dixon analyzes root cause (not just symptoms)
+- Ada implements fix
+- Ada adds regression test
+
+**New Features**:
+
+- Ada reads all cursor rules
+- Ada implements feature
+- Phil reviews if user-facing
+- Ada writes comprehensive tests
+
+**Refactoring**:
+
+- Ada creates safety net (tests for current behavior)
+- Ada refactors incrementally
+- Rivera reviews for architectural issues
+- Dixon checks for subtle bugs
+
+**Research/POCs**:
+
+- Explore agent investigates options
+- Ada implements proof-of-concept
+- Document findings and recommendations
+
+## Key Principles
+
+1. **Single worktree per task**: Clean isolation for parallel development
+2. **Adaptive review**: Review intensity matches task complexity and risk
+3. **Intelligent agent selection**: Right agent for the job, no forced patterns
+4. **Git hooks do validation**: Leverage your existing infrastructure
+5. **Intelligent bot handling**: Distinguish valuable feedback from noise
+6. **PR-centric workflow**: Everything leads to a mergeable pull request
+7. **You control merge**: AI gets it ready, you decide when to ship
+
+## What NOT To Do
+
+- **Don't** create multiple parallel worktrees for one task - complexity disaster
+- **Don't** use forced classification logic - let LLM decide intelligently
+- **Don't** skip git hooks - they're already configured, use them
+- **Don't** do heavy review for trivial changes - scale effort with risk
+
+## Metrics That Matter
+
+**Speed**:
+
+- Bot feedback cycles: Target 0-1 (minimize back-and-forth)
+
+**Quality**:
+
+- First-time merge rate: Target 95%
+- Bot feedback items: Target < 2 per PR
+- Post-merge bugs: Track and minimize
+
+**Autonomy**:
+
+- Human intervention: Only task description + merge decision
+- Agent utilization: Right agent for job, every time
+
+## Next Steps
+
+1. ✅ **Implement `/autotask` command** (`.claude/commands/autotask.md`)
+2. ✅ **Update `/setup-environment`** to use existing git hooks
+3. **Test with real tasks** (start simple, build confidence)
+4. **Iterate and improve** (measure metrics, optimize)
+
+## The Philosophy
+
+**Simple beats complex**: One worktree, clear flow, no magic
+
+**Fast feedback**: Validate locally, catch early, fix immediately
+
+**Intelligent automation**: Right agent, right time, right decision
+
+**Human control**: AI prepares, human decides
+
+This is autonomous development done right - fast, reliable, and always under your
+control.