✈️ Almost Autopilot

⚠️ EXPERIMENTAL PROJECT - WORK IN PROGRESS ⚠️

This is a personal experiment in AI-assisted development workflows using Claude Code. It's a rapidly evolving testbed for exploring how AI tools can augment (not replace) human developers. Consider this a research project, not production-ready tooling.

🚧 Current Status

• Highly experimental - Breaking changes expected
• Personal project - Built for my specific workflow, may not work for yours
• Rough edges - Contains hardcoded paths and assumptions about my development environment
• Active development - Configurations change frequently as I experiment

💡 Research Focus

This project explores practical applications of AI pair programming, specifically:

• How to effectively delegate routine tasks to AI while maintaining code quality
• Creating reusable prompts and configurations for common development patterns
• Understanding the boundaries between AI assistance and human expertise

Experimental Approach

I'm iterating quickly on these configurations as I work on other projects. The general pattern:

1. Hit a repetitive task in my workflow
2. Quickly prototype a configuration or hook
3. Test it on real projects
4. Refine based on what breaks

Note: This means configurations may be overly specific to my setup, contain assumptions about tool versions, or have undocumented dependencies.

What This Attempts To Do

The goal is to reduce friction in my personal development workflow by:

• Automating repetitive quality checks
• Capturing common patterns in reusable configurations
• Experimenting with AI-assisted code review and generation

Important: Your mileage will vary. This is tuned for my specific tech stack and preferences.

📁 Repository Structure

almost-autopilot/
├── README.md                           # This file
├── claude/                             # Claude Code configurations
│   ├── CLAUDE.global.md                # Global development instructions
│   ├── settings.json                   # Claude Code settings
│   ├── agents/                         # Specialized subagents
│   │   ├── ai-development-specialist.md
│   │   ├── code-review-expert.md
│   │   ├── data-specialist.md
│   │   ├── frontend-architect.md
│   │   ├── fullstack-api-developer.md
│   │   ├── geospatial-specialist.md
│   │   ├── infrastructure-specialist.md
│   │   ├── opensource-developer.md
│   │   ├── security-expert.md
│   │   └── testing-qa-automation.md
│   └── hooks/                          # Automation hooks
│       ├── pre-commit-pullitzer.sh     # Pullitzer integration hook
│       ├── pre-commit-quality.sh       # Original quality checks
│       └── prompt-spellcheck.sh        # Typo detection for prompts
└── [future]/                           # Placeholder for other AI tools
    ├── cursor/                         # Cursor AI configurations
    └── copilot/                        # GitHub Copilot settings

🤖 Claude Code Configurations

Global Instructions (claude/CLAUDE.global.md)

Comprehensive development guidelines covering:

• Pre-commit workflows with automated linting and testing
• Commit hygiene with semantic versioning conventions
• Documentation standards focused on current state (no temporal references)
• Package research guidelines to avoid reinventing the wheel
• Cost-conscious cloud infrastructure practices
• Security and best practices for modern development

Specialized Subagents (claude/agents/)

Ten expert subagents for different development domains:

AI Development Specialist

• Claude Code mastery and prompt engineering
• AI tool ecosystem and workflow optimization
• Human-AI collaboration patterns

Code Review Expert

• Architecture and design pattern evaluation
• Security and performance analysis
• Best practices enforcement

Data & Analytics Specialist

• Database modeling and optimization
• Analytics implementation and visualization
• Geographic and climate data handling

Frontend Component Architect

• React, Next.js, Svelte, SvelteKit
• Component systems and responsive design
• Performance optimization and accessibility

Full-Stack API Developer

• Django, FastAPI, SvelteKit server-side
• REST and GraphQL API design
• Database optimization and integration

Geospatial & GIS Specialist

• PostGIS, Google Earth Engine
• Web mapping and spatial analysis
• Coordinate systems and geographic data processing

Infrastructure & DevOps Specialist

• Cloud infrastructure (AWS, GCP, Azure)
• Terraform, Docker, Kubernetes
• CI/CD and deployment automation

Open Source Project Developer

• Project setup, licensing, and documentation
• Community building and contribution management
• Package distribution and release management

Security & Compliance Expert

• Web security and OWASP compliance
• Data privacy (GDPR, CCPA, ISO 27001)
• Authentication and secure coding practices

Testing & QA Automation Specialist

• Comprehensive testing strategies (unit, integration, e2e)
• Jest, pytest, Playwright automation
• CI/CD test integration

Quality Hooks (claude/hooks/)

Pre-commit Quality Hook

Automated pre-commit validation that runs:

• Linting & Formatting: Detects and runs appropriate linters for:

  • Python (ruff, black, flake8, custom scripts)
  • JavaScript/TypeScript (ESLint, Prettier)
  • Markdown (markdownlint)
  • Go (golangci-lint, gofmt)
  • Rust (cargo fmt, cargo clippy)
  • YAML (yamllint)
  • Terraform (terraform fmt, validate, tflint, checkov)

• Type Checking: Validates types across languages:

  • Python (mypy, pyright)
  • TypeScript (tsc, npm scripts)
  • Go (go vet, go build)
  • Rust (cargo check)

Prompt Spellcheck Hook

Carbon-conscious prompt validation that:

• Reduces wasted tokens: Catches typos before AI misinterprets them
• Smart filtering: Ignores code blocks and common technical terms
• Non-blocking: Shows warnings and gives 3 seconds to cancel with Ctrl+C
• Requires: aspell (brew install aspell on macOS)

⚙️ Setup (At Your Own Risk)

⚠️ WARNING: This setup assumes specific directory structures and tool versions. Adapt as needed for your environment.

Experimental Setup

# Clone this repository (update with your fork)
git clone https://github.com/[YOUR-USERNAME]/almost-autopilot.git ~/almost-autopilot

# Create symlink for Claude Code (adjust paths as needed)
ln -s ~/almost-autopilot/claude ~/.claude

# Make hooks executable
chmod +x ~/.claude/hooks/*.sh

# Install dependencies (versions may vary)
brew install aspell  # macOS - required for spellcheck hook
# apt-get install aspell  # Linux

Note: Paths are hardcoded for my macOS setup. You'll likely need to adjust them.

Managing Updates

Since this is experimental, I update frequently and break things:

cd ~/almost-autopilot  # or wherever you cloned it
git pull  # May contain breaking changes

🔄 Usage

These configurations work automatically with Claude Code:

• Global instructions are applied to all projects
• Hooks run automatically before commits
• Subagents can be invoked using Claude Code's Task tool

Example subagent usage:

Use the infrastructure specialist to optimize our AWS costs
Have the frontend architect review our component structure
Ask the security expert to audit our authentication flow

📝 Maintenance

Regular updates to consider:

• New linting tools and configurations
• Updated security best practices
• Additional specialized subagents
• Framework-specific guidelines
• Cloud platform updates

⚠️ Limitations & Known Issues

• Hardcoded paths: Many configurations assume my specific directory structure
• macOS-centric: Primarily tested on macOS, may need adjustments for Linux/Windows
• Tool version assumptions: Expects specific versions of tools that may differ from yours
• Incomplete documentation: This is a personal project, so documentation is minimal
• No tests: These are configurations, not production code - use at your own risk
• Rapid changes: I update this frequently as I experiment, without regard for backward compatibility

🤝 About This Project

This is a personal exploration of AI-augmented development workflows. It's:

• Not production-ready: This is experimental code for learning and exploration
• Not officially supported: No warranties, guarantees, or support provided
• Not best practices: These are my personal experiments, not industry standards
• Rapidly changing: I modify these configurations frequently as I learn

If you find it useful as a reference for your own experiments, great! But please don't expect it to work out of the box or to follow conventional software engineering practices.

🛩️ About the Name

"Almost Autopilot" captures the reality of AI-assisted development: like aircraft autopilot, AI can handle routine tasks and keep you on course, but you still need a human pilot for takeoff, landing, and handling unexpected turbulence. The AI might be flying the plane most of the time, but you better be ready to grab the controls when it starts heading toward a mountain.

It's a reminder that even the best AI tools are assistants, not replacements. They're "almost" autopilot – close enough to be incredibly useful, but not quite enough to let you sleep in the cockpit.

---

This is an experimental project exploring AI-assisted development. Use at your own risk and expect breaking changes.