# __persuade__
## _Software Development in the Age of AI_

[![Python Code Quality](https://github.com/stavxyz/persuade/actions/workflows/python-quality.yml/badge.svg)](https://github.com/stavxyz/persuade/actions/workflows/python-quality.yml)
[![PyPI - Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **The complete automation framework for AI-assisted software development**

A production-ready template repository that transforms your development workflow with Claude Code automation, comprehensive knowledge bases, and battle-tested engineering standards. Distribute automation to all your projects with a single command.

## What You Get

### 🤖 Persuade CLI - One-Command Automation Sync

A powerful Python package that syncs Claude Code automation to any project:

```bash
# Install (within virtual environment)
python3 -m venv .venv && source .venv/bin/activate
pip install git+https://github.com/stavxyz/persuade.git

# Sync to any project
persuade sync                    # Current directory
persuade sync ~/projects/my-app  # Specific project

# Preview changes first
persuade sync --dry-run
```

**Features:**
- **Smart syncing** with automatic backups (manual rollback available)
- **Settings merging** that preserves your project configs
- **Shadow mode** for open-source projects (keeps .claude/ out of git)
- **Editable mode** for template development with live updates
- **Doctor command** to validate and fix configurations

### 🔄 Automated PR Review Loop

GitHub Actions workflows that supercharge your development:

- **Claude-powered PR reviews** - Automatic code review against engineering standards
- **@mention automation** - Summon Claude in issues/PRs with `@claude [task]`
- **Quality gates** - Automated linting, formatting, type checking, and testing
- **ShellCheck validation** - Ensure shell scripts meet quality standards

Simply push code → get automated feedback → iterate faster.

### 📚 Comprehensive Knowledge Base

Production-ready guidance for AI assistants and developers:

- **Engineering standards** - Python, testing, documentation requirements
- **Critical rules** - Non-negotiable requirements (no main pushes, venv usage, etc.)
- **Tactical knowledge** - How-tos for git, testing, infrastructure, and more
- **Guidelines system** - Structured rules for PR feedback classification (Parlant-style)
- **Model nuances** - Specific guidance for Claude, GPT-4, and other AI models

### 🎯 Git Protection & Hooks

Prevent common mistakes with automatic protection:

- **Pre-push hooks** - Block direct pushes to main/master
- **Virtual environment checks** - Prevent system Python pollution
- **Auto-installation** - Hooks install automatically when you sync

### 📖 Living Documentation

Organized resources for every phase of development:

- **Methodologies** - AI pair programming approaches and patterns
- **Playbooks** - Step-by-step guides for features, bugs, refactoring
- **Prompts** - Reusable templates for code generation, review, debugging
- **Tips & tricks** - Battle-tested techniques organized by category
- **Examples** - Before/after comparisons, good/bad PR examples
- **Specs** - Standards for code quality, testing, and security

## 🚀 Quick Start

### Prerequisites

**Install Claude Code (Native)** - Required for automation features:

```bash
# macOS/Linux
curl -fsSL https://desktop-releases.anthropic.com/install.sh | sh

# Windows
irm https://desktop-releases.anthropic.com/install.ps1 | iex

# Verify
claude doctor  # Should show version 2.0.58+
```

📖 **Full guide**: [docs/installing-claude-code.md](./docs/installing-claude-code.md)

### Install Persuade

```bash
# Install from source (recommended for now)
git clone https://github.com/stavxyz/persuade.git
cd persuade
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Verify installation
persuade --version
```

### Sync to Your Project

```bash
# Preview what will be synced
persuade sync --dry-run ~/projects/my-app

# Apply the sync
persuade sync ~/projects/my-app
```

**What gets synced:**
- `.claude/` directory with all automation
- Git hooks (auto-installed to `.git/hooks/`)
- Engineering standards and knowledge base
- PR iteration workflow (`/iterate-pr` command)
- Permissions for frictionless Claude Code usage
- GitHub Actions workflows (optional)

### Enable GitHub Automation (Optional)

Add workflows to your project for CI/CD automation:

1. **Add secrets** to your GitHub repository:
   - `ANTHROPIC_API_KEY` - Get from https://console.anthropic.com/settings/keys

2. **Workflows sync automatically** when you run `persuade sync`

3. **Test the automation**:
   ```bash
   # Create a PR
   git checkout -b test-feature
   git commit -m "test: automation"
   git push -u origin test-feature
   gh pr create

   # Claude will automatically review your PR
   # Comment with @claude to interact
   ```

📖 **Full workflow guide**: [.github/workflows/README.md](./.github/workflows/README.md)

## 📂 Repository Structure

### Core Directories

```
.
├── persuade/              # 🔧 Python package for automation sync
│   ├── cli.py            # CLI commands (sync, doctor, rollback)
│   ├── core.py           # Smart sync logic
│   ├── settings_merger.py # JSON settings merge
│   └── agents/           # Agent integrations (optional)
│
├── .claude/              # 🤖 Claude Code automation system
│   ├── commands/         # Custom slash commands (/iterate-pr)
│   ├── hooks/            # Event handlers (post-pr-create)
│   ├── git-hooks/        # Git protection (pre-push)
│   ├── scripts/          # Automation scripts (legacy sync tool)
│   ├── standards/        # AI-optimized engineering standards
│   ├── knowledge/        # Tactical how-to guides + PR feedback rules
│   └── settings.json     # Permissions configuration
│
├── .github/workflows/    # 🔄 CI/CD automation
│   ├── claude-pr-review.yml      # Automatic PR reviews
│   ├── claude-on-mention.yml     # @claude in issues/PRs
│   ├── python-quality.yml        # Linting, testing, type checking
│   └── shellcheck.yml            # Shell script validation
│
├── methodologies/        # 🧠 Development approaches
├── playbooks/            # 📖 Step-by-step guides
├── prompts/              # 💬 Reusable prompt templates
├── tips-and-tricks/      # 💡 Practical techniques
├── model-nuances/        # 🎯 AI model-specific guidance
├── specs/                # 📋 Standards and requirements
├── examples/             # 📚 Before/after demonstrations
├── templates/            # 📝 Quick-start templates
├── docs/                 # 📖 Comprehensive guides
└── tests/                # ✅ Test suite for persuade package
```

## 🎓 How to Use This Repository

### For Developers

**Sync automation to your projects:**
```bash
persuade sync ~/projects/my-app
```

**Browse by need:**
- Need to implement a feature? → [`playbooks/implementing-new-feature.md`](./playbooks/implementing-new-feature.md)
- Want better prompts? → [`prompts/`](./prompts)
- Learning a new AI tool? → [`model-nuances/`](./model-nuances)

**Use as reference:**
- Check engineering standards in [`.claude/standards/`](./.claude/standards/)
- Browse knowledge base in [`.claude/knowledge/`](./.claude/knowledge/)
- Find guidelines in [`.claude/knowledge/pr-feedback/`](./.claude/knowledge/pr-feedback/)

### For Teams

**Template repository approach:**
1. Fork this repository for your organization
2. Customize standards in `.claude/standards/`
3. Add team-specific knowledge to `.claude/knowledge/`
4. Team members sync to their projects with `persuade sync`
5. Updates propagate with `persuade sync` (preserves local configs)

### For AI Assistants

**Essential reading order:**
1. [`.claude/standards/CLAUDE_CODE_RULES.md`](./.claude/standards/CLAUDE_CODE_RULES.md) - Non-negotiable requirements
2. [`.claude/standards/ENGINEERING_STANDARDS.md`](./.claude/standards/ENGINEERING_STANDARDS.md) - Coding standards
3. [`.claude/knowledge/README.md`](./.claude/knowledge/README.md) - Tactical knowledge index
4. [`.claude/knowledge/pr-feedback/README.md`](./.claude/knowledge/pr-feedback/README.md) - Structured rules

## 🔧 Persuade CLI Commands

**⚠️ Git Repository Required**: Persuade commands require a git repository by default and automatically resolve to the repository root. This ensures automation is properly version-controlled and auditable.

**Smart path resolution**:
- Run from any subdirectory → automatically resolves to git root
- Run without a path → uses current directory, resolved to git root
- Use `--no-resolve-root` to stay in current/specified subdirectory
- Use `--allow-non-git` for non-git directories (not recommended)

### `persuade sync`
Sync automation to target project with intelligent merging.

```bash
persuade sync                                # Git root of current directory
persuade sync ~/projects/my-app              # Git root of specified path
persuade sync --dry-run                      # Preview changes
persuade sync --shadow ~/projects/my-app     # Exclude from git
persuade sync --editable ~/projects/my-app   # Symlink for development
persuade sync --no-resolve-root              # Stay in current subdirectory
persuade sync --allow-non-git ~/legacy       # Sync non-git directory (not recommended)
```

### `persuade doctor`
Validate configuration and fix issues.

```bash
persuade doctor                              # Check git root of current directory
persuade doctor ~/projects/my-app            # Check git root of specified path
persuade doctor --fix                        # Auto-fix problems
persuade doctor --no-resolve-root            # Check current subdirectory only
persuade doctor --allow-non-git ~/legacy     # Check non-git directory
```

### `persuade rollback`
Restore from automatic backup.

```bash
persuade rollback --list                     # Show backups (git root)
persuade rollback --latest                   # Restore most recent
persuade rollback --list ~/projects/my-app   # Show backups (specific project)
persuade rollback --no-resolve-root --list   # Show backups (current subdirectory)
persuade rollback --allow-non-git ~/legacy   # Restore to non-git directory
```

### `persuade validate-docs`
Validate Python code examples in documentation.

```bash
persuade validate-docs                       # Check all docs
persuade validate-docs --strict             # With mypy type checking
```

📖 **Full CLI documentation**: [persuade/README.md](./persuade/README.md)

## 🤖 GitHub Actions Features

### Claude PR Review
Automatically reviews pull requests against engineering standards:
- Code quality and best practices
- Python standards (type hints, error handling, logging)
- Testing coverage and quality
- Documentation completeness

### Claude on @mention
Summon Claude in issues and PRs:
```
@claude review the error handling in this function
@claude add unit tests for the new feature
@claude explain how this workflow works
```

### Python Quality Checks
Automated validation on every PR:
- **Linting** with ruff
- **Formatting** with ruff format
- **Type checking** with mypy
- **Testing** with pytest + coverage

### ShellCheck
Ensures shell scripts meet quality standards with zero-tolerance for global disables.

📖 **Setup guide**: [.github/workflows/README.md](./.github/workflows/README.md)

## 📚 Documentation Hub

### Getting Started
- [**Quick Start**](./QUICKSTART.md) - Get up and running in 5 minutes
- [**Installing Claude Code**](./docs/installing-claude-code.md) - Platform-specific instructions
- [**Using .CLAUDE Template**](./docs/using-claude-template.md) - Project configuration guide
- [**Syncing Automation**](./docs/syncing-automation.md) - Distribute to your projects

### Core Guides
- [**Prompt Engineering**](./docs/prompt-engineering-guide.md) - Master effective prompting
- [**Claude Code Best Practices**](./docs/claude-code-best-practices.md) - Optimize your workflow
- [**Engineering Standards**](./.claude/standards/ENGINEERING_STANDARDS.md) - Comprehensive standards (human-facing)

### Automation System
- [**Claude Code Automation**](./.claude/README.md) - Complete system overview
- [**Persuade CLI**](./persuade/README.md) - Package documentation
- [**GitHub Workflows**](./.github/workflows/README.md) - CI/CD automation

## 💡 Key Features Explained

### Smart Settings Merging

When syncing, Persuade intelligently merges `settings.json`:
- **Template permissions** are added
- **Your custom permissions** are preserved
- **Conflicts** are handled gracefully
- **Backups** are automatic

### File Categorization

Persuade categorizes files for intelligent sync behavior:

| Category | Behavior | Examples |
|----------|----------|----------|
| **SYNC_ALWAYS** | Always overwrite | Commands, hooks, scripts |
| **MERGE_SMART** | Intelligent merge | settings.json |
| **SKIP_ALWAYS** | Never sync | settings.local.json, state/, logs/ |
| **COPY_IF_MISSING** | Copy once | README, documentation |

### Shadow Mode

Perfect for open-source projects where you want automation but don't want to expose `.claude/` in your repository:

```bash
persuade sync --shadow ~/projects/open-source-app
```

Creates automation locally and adds to `.gitignore` automatically.

### Editable Mode

For template developers who want live updates:

```bash
persuade sync --editable ~/projects/test-app
```

Symlinks files instead of copying - changes to template reflect immediately in target project.

## 🎯 Common Scenarios

### Scenario 1: New Project Setup
```bash
# Clone template
git clone https://github.com/stavxyz/persuade.git
cd persuade
pip install -e .

# Sync to new project
persuade sync ~/projects/new-app

# Start developing with full automation
cd ~/projects/new-app
git checkout -b feature/first-feature
# ... make changes ...
git push
gh pr create  # Claude will review automatically
```

### Scenario 2: Update Existing Projects
```bash
# Pull latest template updates
cd persuade
git pull

# Preview changes first
persuade sync --dry-run ~/projects/app-1
persuade sync --dry-run ~/projects/app-2
persuade sync --dry-run ~/projects/app-3

# Re-sync to all your projects (preserves their configs)
persuade sync ~/projects/app-1
persuade sync ~/projects/app-2
persuade sync ~/projects/app-3
```

### Scenario 3: Open Source Project
```bash
# Use shadow mode to keep automation local
persuade sync --shadow ~/projects/my-oss-project

# Automation works locally, not committed to repo
# Perfect for contributors who want the tooling
```

## 🔍 Finding Content

### By Task
- **Implementing features**: `playbooks/implementing-new-feature.md`, `prompts/code-generation/`
- **Fixing bugs**: `tips-and-tricks/debugging/`, `prompts/debugging/`
- **Writing tests**: `prompts/testing/`, `tips-and-tricks/testing/`
- **Refactoring**: `prompts/refactoring/`, `tips-and-tricks/refactoring/`
- **Code review**: `prompts/code-review/`, `playbooks/`
- **Infrastructure**: `.claude/knowledge/infrastructure/`

### By AI Model
- **Claude 3.5 Sonnet**: `model-nuances/claude-3-5-sonnet.md`
- **GPT-4**: `model-nuances/gpt-4.md` (contribute as you learn)
- **Copilot**: `model-nuances/copilot.md` (contribute as you learn)

### By Component
- **Automation system**: `.claude/README.md`
- **CLI tool**: `persuade/README.md`
- **GitHub workflows**: `.github/workflows/README.md`
- **Engineering standards**: `.claude/standards/ENGINEERING_STANDARDS.md`
- **Knowledge base**: `.claude/knowledge/README.md`

## 💡 Contributing

This is designed for **iterative, continuous learning**.

**Quick contributions:**
- Found a useful tip? → Add to `tips-and-tricks/`
- Discovered an AI quirk? → Document in `model-nuances/`
- Created an effective prompt? → Save in `prompts/`
- Developed a workflow? → Add to `playbooks/`
- Improved automation? → Enhance `persuade/` or `.claude/`

**Philosophy**: Raw notes > perfect documentation. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details.

### Development Workflow

```bash
# Clone and setup
git clone https://github.com/stavxyz/persuade.git
cd persuade
just setup  # Creates venv, installs deps, sets up git hooks

# Or manually:
# python3 -m venv .venv && source .venv/bin/activate
# pip install -e ".[dev]"
# lefthook install

# Make changes
git checkout -b feature/my-improvement

# Run all quality checks
just check  # lint, format-check, typecheck, test

# Or run individually:
just lint        # Run linter
just test        # Run tests
just test-cov    # Run tests with coverage

# Validate docs
persuade validate-docs --strict

# Commit and push
git add .
git commit -m "feat: description"
git push -u origin feature/my-improvement
gh pr create  # Claude will review!
```

## 🎓 Learning Path

**New to AI-assisted development?**

1. Read [**Quick Start Guide**](./QUICKSTART.md)
2. Install and sync: `persuade sync ~/projects/test-app`
3. Read [`methodologies/ai-pair-programming.md`](./methodologies/ai-pair-programming.md)
4. Follow a playbook for your next task
5. Save effective prompts as you find them
6. Contribute your learnings

**Experienced with AI coding?**

- Sync automation to your projects
- Add your battle-tested prompts
- Document model quirks you've found
- Share your workflows
- Improve the automation system

## 🎯 Key Principles

1. **Automation first** - Let tools handle repetitive tasks
2. **Practical over theoretical** - Focus on what works in real development
3. **Quick capture over perfection** - Document now, refine later
4. **Experience-based** - Real discoveries from actual development
5. **Tool-agnostic** - Works with Claude, GPT-4, Copilot, and others
6. **Always evolving** - Update as tools and practices improve

## 🛠️ Technical Details

### Requirements
- **Python**: 3.11+
- **Claude Code**: 2.0.58+ (native installation)
- **Dependencies**: click, rich (auto-installed with persuade)
- **Optional**: [just](https://github.com/casey/just) (command runner), [lefthook](https://github.com/evilmartians/lefthook) (git hooks)

### Testing
- **Framework**: pytest with coverage reporting
- **Standards**: 80% coverage minimum
- **Quality**: ruff linting, mypy type checking
- **CI/CD**: Automated via GitHub Actions

### Architecture
- **Modular design**: Separate concerns (sync, merge, backup, validation)
- **Type-safe**: Full mypy strict mode
- **Well-tested**: Comprehensive unit and integration tests
- **Documented**: Inline docstrings + external guides

### Security Scanning
This project uses multiple layers of security scanning in CI/CD:

#### Dependency Scanning (Blocking)
- **pip-audit**: Blocks CI on known vulnerabilities in dependencies (CVE database)

#### Code Analysis (Non-blocking)
- **safety**: Additional vulnerability database checks
- **bandit**: Static analysis for Python security anti-patterns

#### GitHub Advanced Security (Optional)
If GitHub Code Security is enabled, CodeQL analysis provides additional coverage.

**To enable** (available for public repos or GitHub Team/Enterprise):
1. Navigate to Settings → Security & analysis
2. Find "Code scanning" section
3. Click "Enable" and configure default setup for Python

The existing multi-layer approach provides comprehensive security even without CodeQL.

## 🤝 Community & Support

- **Issues**: [GitHub Issues](https://github.com/stavxyz/persuade/issues)
- **Discussions**: [GitHub Discussions](https://github.com/stavxyz/persuade/discussions)
- **Contributing**: [CONTRIBUTING.md](./CONTRIBUTING.md)
- **Security**: [.github/SECURITY.md](./.github/SECURITY.md)

## 📝 License

MIT License - See [LICENSE](./LICENSE)

## 🙏 Acknowledgments

Built on lessons learned from daily AI-assisted development with:
- **Claude** (Anthropic) - AI pair programming
- **GPT-4** (OpenAI) - Code generation
- **GitHub Copilot** - Inline suggestions
- **Broader community** - Collective wisdom

Special thanks to all contributors who help make this repository a comprehensive resource for AI-assisted development.

## 🚀 What's Next?

### Immediate: Try It Now
```bash
# Get started in 2 minutes
git clone https://github.com/stavxyz/persuade.git
cd persuade
pip install -e .
persuade sync ~/projects/my-app
```

### Short-term: Explore
- Browse the knowledge base
- Try the playbooks
- Customize for your team
- Contribute your learnings

### Long-term: Automation Roadmap
- Pre-PR quality gates (auto-lint, format, security scan)
- Test generation based on review feedback
- Review pattern learning and knowledge base
- Predictive feedback analysis
- End-to-end `/ship` command automation from code to production

---

**Remember**: This is a tool for working developers. Make it useful for you. Quick notes are better than lost knowledge. Automation should speed you up, not slow you down.

**Ready to supercharge your AI-assisted development?** Start with `persuade sync` and experience the difference. 🚀
