BaseProject Template - Complete Usage Guide

Note: This file will be automatically deleted after running setup.sh. It contains detailed instructions for using this template to create your new project.

Getting Started
Quick Setup (Recommended)
Step-by-Step Manual Setup
Customization Guide
Multi-Language Support
Feature Configuration
File-by-File Explanation
Troubleshooting

Getting Started

Prerequisites

Before you begin, make sure you have:

Git installed (git --version to check)
Claude Code CLI installed (Installation guide)
Language tools for your project (optional):
- Python: UV or pip
- JavaScript/TypeScript: Node.js and pnpm/npm
- Go: Go toolchain
- Rust: Cargo

Two Ways to Use This Template

Option 1: GitHub Template (Recommended)

Click the green "Use this template" button on GitHub
Create your new repository
Clone your new repo: git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
Jump to Quick Setup

Option 2: Direct Clone

git clone https://github.com/AutumnsGrove/BaseProject.git YourProjectName
cd YourProjectName
rm -rf .git  # Remove template's git history
git init     # Start fresh

Quick Setup (Recommended)

The fastest way to set up your project is using the interactive setup script:

cd your-project-directory
bash setup.sh

What the Setup Script Does

The script will:

Ask you questions about your project:
- Project name (e.g., "MyAwesomeApp")
- Brief description
- Primary programming language
- API keys you'll need
- Whether to install git hooks
Automatically configure:
- Update AGENT.md with your project details
- Create README.md with your project name
- Generate secrets_template.json for your API keys
- Initialize language-specific dependencies
- Set up project structure (src/, tests/)
Clean up template files:
- Remove this TEMPLATE_USAGE.md file
- Remove setup.sh itself
- Remove template-specific sections from README
Initialize git (if requested):
- Create initial commit with proper format
- Install git hooks for code quality

Example Setup Session

$ bash setup.sh

╔══════════════════════════════════════════════════════════════╗
║         BaseProject Template Setup                           ║
╚══════════════════════════════════════════════════════════════╝

This script will help you customize BaseProject for your needs.
All template files will be cleaned up automatically.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project Configuration
─────────────────────

📝 Project name: MyWeatherApp
📝 Brief description: A CLI tool for weather forecasting with AI

🔧 Primary language:
   1) Python    2) JavaScript    3) Go    4) Rust    5) Other

   Your choice: 1

🔑 Which API keys will you need? (space-separated numbers)
   1) Anthropic    2) OpenAI    3) OpenRouter    4) AWS    5) Other

   Your choices: 1 3

🎣 Install git hooks for code quality and security? [y/N]: y

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Setting up your project...

✓ Created backup at .backup-20250119-143022/
✓ Updated AGENT.md with project details
✓ Transformed README.md (removed template sections)
✓ Created secrets_template.json with Anthropic and OpenRouter keys
✓ Initialized Python project with UV (pyproject.toml created)
✓ Created src/ directory with __init__.py
✓ Created tests/ directory with test_example.py
✓ Created TODOS.md with project-specific tasks
✓ Installed git hooks (pre-commit, commit-msg, pre-push)
✓ Git initialized with initial commit
✓ Cleaned up template files (TEMPLATE_USAGE.md, setup.sh)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎉 Setup Complete!

Your project is ready. Next steps:

1. Review AGENT.md - Your main project instructions
2. Check TODOS.md - Initial tasks have been added
3. Set up secrets:
   cp secrets_template.json secrets.json
   # Edit secrets.json with your real API keys

4. Start developing:
   claude "your task here"

5. Skills are automatically available! Use them when needed:
   - secrets-management, database-management, git-workflows, etc.
   - See AGENT.md for the full list of available skills

Happy coding! 🚀

Step-by-Step Manual Setup

If you prefer full control or the automated script isn't working, follow these manual steps:

1. Customize AGENT.md

Open AGENT.md and fill in the placeholders:

## Project Purpose
[Fill in: What this project does - 1-2 sentences]

Replace with:

## Project Purpose
A command-line weather forecasting tool that uses AI to provide personalized weather insights.

Do the same for:

Tech Stack section (lines 11-15)
Architecture Notes section (line 18)

2. Set Up Secrets Management

If your project uses API keys:

# Create secrets template
cat > secrets_template.json << 'EOF'
{
  "anthropic_api_key": "your-key-here",
  "openai_api_key": "your-key-here",
  "comment": "Copy to secrets.json and add real keys"
}
EOF

# Create your actual secrets file (gitignored)
cp secrets_template.json secrets.json

# Edit with real keys
nano secrets.json

3. Initialize Your Language Environment

Python (with UV)

uv init
# This creates pyproject.toml

JavaScript/TypeScript

pnpm init
# This creates package.json

Go

go mod init github.com/yourusername/yourproject

Rust

cargo init

4. Create Project Structure

# Create source directory
mkdir -p src
touch src/__init__.py  # For Python
# OR
touch src/index.js     # For JavaScript
# OR
touch src/main.go      # For Go

# Create tests directory
mkdir -p tests
touch tests/__init__.py         # For Python
touch tests/test_example.py     # Example test

5. Install Git Hooks (Optional but Recommended)

cd AgentUsage/pre_commit_hooks
bash install_hooks.sh

# Follow the prompts - the installer will:
# - Detect your project language automatically
# - Install appropriate hooks (formatters, linters, security scanner)
# - Back up any existing hooks

6. Update README.md

Remove the template-specific sections (marked with  and ):

Quick Start section (Options 1, 2, Manual Setup)
Customization Workflow section
Template-specific troubleshooting items
Keeping BaseProject Updated section
What's Next section

Add your project name and description at the top.

7. Create Initial TODOS.md

cat > TODOS.md << 'EOF'
# Project TODOs

## Setup Tasks
- [x] Customize CLAUDE.md
- [x] Set up secrets.json
- [ ] Add project dependencies
- [ ] Write initial tests

## Development Tasks
- [ ] Implement core feature X
- [ ] Add error handling
- [ ] Write documentation

## Testing Tasks
- [ ] Unit tests for core logic
- [ ] Integration tests
- [ ] End-to-end tests
EOF

8. Clean Up Template Files

# Remove template-specific files
rm -f TEMPLATE_USAGE.md
rm -f setup.sh
rm -f .github/workflows/setup-template.yml

9. Initialize Git

# If not already initialized
git init

# Make initial commit
git add .
git commit -m "feat: initialize project from BaseProject template

- Set up project structure
- Configured CLAUDE.md with project details
- Added secrets management
- Installed git hooks"

Customization Guide

AGENT.md Customization

The AGENT.md file is your project's main instruction manual for AI agents. Customize these sections:

Project Purpose

Be specific about what your project does:

## Project Purpose
A REST API for managing restaurant reservations with real-time availability tracking and SMS notifications.

Tech Stack

List all technologies you're using:

## Tech Stack
- Language: Python 3.11+
- Framework: FastAPI
- Key Libraries: SQLAlchemy, Celery, Twilio SDK
- Package Manager: UV
- Database: PostgreSQL
- Message Queue: Redis

Architecture Notes

Document key architectural decisions:

## Architecture Notes
- Microservices architecture with separate services for bookings, notifications, and analytics
- Event-driven communication using Redis pub/sub
- PostgreSQL for transactional data, Redis for caching
- Celery for async task processing (SMS, emails)

Secrets Configuration

Different projects need different API keys. Here's how to set up common scenarios:

AI/ML Projects

{
  "anthropic_api_key": "sk-ant-api03-...",
  "openai_api_key": "sk-...",
  "huggingface_token": "hf_...",
  "comment": "Keys for AI model APIs"
}

Cloud Projects

{
  "aws_access_key_id": "AKIA...",
  "aws_secret_access_key": "...",
  "aws_region": "us-east-1",
  "comment": "AWS credentials for cloud resources"
}

Web Services

{
  "stripe_api_key": "sk_test_...",
  "sendgrid_api_key": "SG....",
  "google_maps_api_key": "AIza...",
  "comment": "Third-party service API keys"
}

Multi-Language Support

BaseProject supports multiple programming languages with language-specific guides and git hooks.

Python Projects

Setup:

# Using UV (recommended)
uv init
uv add fastapi uvicorn sqlalchemy

# Using pip
pip install -r requirements.txt

Structure:

YourProject/
├── src/
│   ├── __init__.py
│   ├── main.py
│   └── models.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── pyproject.toml
└── secrets.json

Git Hooks: Black (formatter), Ruff (linter), pytest (tests)

Guides:

AgentUsage/uv_usage.md - UV package manager
AgentUsage/db_usage.md - Database patterns
AgentUsage/testing_strategies.md - Python testing

JavaScript/TypeScript Projects

Setup:

pnpm init
pnpm add express typescript @types/node

Structure:

YourProject/
├── src/
│   ├── index.ts
│   └── routes.ts
├── tests/
│   └── index.test.ts
├── package.json
└── tsconfig.json

Git Hooks: Prettier (formatter), ESLint (linter), Jest (tests)

Guides:

AgentUsage/multi_language_guide.md - JavaScript patterns

Go Projects

Setup:

go mod init github.com/yourusername/yourproject
go get github.com/gin-gonic/gin

Structure:

YourProject/
├── cmd/
│   └── main.go
├── internal/
│   └── handlers.go
├── go.mod
└── go.sum

Git Hooks: gofmt (formatter), golint (linter), go test (tests)

Rust Projects

Setup:

cargo init
cargo add tokio axum

Structure:

YourProject/
├── src/
│   ├── main.rs
│   └── lib.rs
├── tests/
│   └── integration_test.rs
└── Cargo.toml

Git Hooks: rustfmt (formatter), clippy (linter), cargo test (tests)

Multi-Language Projects

If your project uses multiple languages (e.g., Python backend + JavaScript frontend):

Run setup for each language in their respective directories

Install multi-language git hooks:

cd AgentUsage/pre_commit_hooks
cp pre-commit-multi-language ../../.git/hooks/pre-commit
chmod +x ../../.git/hooks/pre-commit

Organize by directories:

YourProject/
├── backend/          # Python
│   ├── src/
│   └── pyproject.toml
├── frontend/         # JavaScript
│   ├── src/
│   └── package.json
└── CLAUDE.md         # Root instructions

Feature Configuration

Git Hooks (Recommended)

Git hooks provide automatic code quality checks. Choose what to install:

Code Quality Hooks:

pre-commit - Format and lint before commits
commit-msg - Validate commit message format
pre-push - Run tests before pushing

Security Hooks:

pre-commit-secrets-scanner - Prevent committing API keys

Workflow Hooks:

post-checkout - Auto-update dependencies on branch switch
post-commit - Show TODO summary

Install all:

./AgentUsage/pre_commit_hooks/install_hooks.sh

Install specific hooks:

cp AgentUsage/pre_commit_hooks/pre-commit-secrets-scanner .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Database Setup

If your project uses a database, follow the database.py pattern:

Use the skill:
```
skill: "database-management"
```
Create database.py:
- All SQL isolated in one file
- Function-based interface for the rest of your app
- The skill provides the complete template

Update AGENT.md:

## Architecture Notes
- SQLite database with isolated database.py interface
- All SQL queries in database.py, application code uses functions

Docker Support

To add Docker to your project:

Use the skill:
```
skill: "docker-workflows"
```

Add to AGENT.md:

## Architecture Notes
- Containerized with Docker for consistent environments
- Multi-stage builds for production optimization

The skill will guide you through:
- Dockerfile creation
- docker-compose configuration
- Multi-stage builds for production

CI/CD Workflows

To add GitHub Actions:

Use the skill:
```
skill: "cicd-automation"
```
The skill will help you:
- Create .github/workflows/ directory
- Set up testing workflows
- Configure linting and deployment pipelines

File-by-File Explanation

Root Files

File	Purpose	Customize?
`CLAUDE.md`	Redirect to AGENT.md	❌ No - Keep as-is
`AGENT.md`	Main instructions for AI agents	✅ Yes - Fill placeholders
`README.md`	Project documentation	✅ Yes - After setup
`TODOS.md`	Task tracking	✅ Yes - Add your tasks
`.gitignore`	Files to exclude from git	✅ Maybe - Add project-specific patterns
`secrets.json`	API keys (gitignored)	✅ Yes - Add your keys
`secrets_template.json`	Template for API keys	✅ Yes - Document needed keys
`TEMPLATE_USAGE.md`	This file	❌ No - Auto-deleted
`setup.sh`	Setup script	❌ No - Auto-deleted

.claude/skills/ Directory (Skills)

This project uses Claude Code Skills for specialized workflows. Skills are invoked automatically when needed.

Skill	Purpose
`secrets-management`	API keys, credentials
`database-management`	SQLite, database.py patterns
`git-workflows`	Commits, branching
`uv-package-manager`	Python dependencies
`python-testing`	pytest patterns
`docker-workflows`	Containerization
`cicd-automation`	GitHub Actions

Skills are the primary mechanism - use them via the Skill tool.

AgentUsage/ Directory (Extended Reference)

Extended documentation for when you need more detail than skills provide.

Keep this directory as-is - it's reference material for deep dives.

AgentUsage/templates/

Templates for common configuration files:

secrets_template.json - API keys template
.env.example - Environment variables
pyproject.toml.example - Python UV configuration

Copy and customize as needed.

AgentUsage/pre_commit_hooks/

Git hooks for code quality and security:

install_hooks.sh - Interactive installer
Various hook files for different checks
TROUBLESHOOTING.md - Hook issues help

Run the installer to set up hooks automatically.

Troubleshooting

Setup Script Issues

"bash: setup.sh: Permission denied"

chmod +x setup.sh
bash setup.sh

"UV not found" (Python projects)

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# OR use pip fallback
python -m pip install uv

"Git hooks installation failed"

# Make hooks executable
chmod +x AgentUsage/pre_commit_hooks/*

# Run installer manually
cd AgentUsage/pre_commit_hooks
bash install_hooks.sh

Configuration Issues

"AGENT.md not updating"

Make sure you've replaced the [Fill in: ...] placeholders with actual text.

"Secrets not loading"

Verify secrets.json exists and has valid JSON
Check file permissions: chmod 600 secrets.json
Make sure secrets.json is in .gitignore

"Git hooks not running"

# Check hook files exist
ls -la .git/hooks/

# Make them executable
chmod +x .git/hooks/*

# Test manually
.git/hooks/pre-commit

Language-Specific Issues

Python: "Module not found"

# UV
uv sync

# Pip
pip install -r requirements.txt

JavaScript: "Cannot find module"

pnpm install
# OR
npm install

Go: "Package not found"

go mod download

Git Issues

"Not a git repository"

git init

"Author identity unknown"

git config user.name "Your Name"
git config user.email "your.email@example.com"

Still Having Issues?

Use relevant skills:
- skill: "git-hooks" for hook issues
- skill: "python-testing" for test issues
- Other skills as appropriate
Check extended documentation:
- AgentUsage/pre_commit_hooks/TROUBLESHOOTING.md for hook issues
- AgentUsage/multi_language_guide.md for language-specific help

Ask Claude Code for help:

claude "I'm having trouble with [specific issue]"

Open an issue on GitHub: https://github.com/AutumnsGrove/BaseProject/issues

Next Steps After Setup

Once setup is complete:

Review your AGENT.md - Make sure all sections are filled in
Check TODOS.md - Initial tasks should be listed
Set up real secrets - Copy secrets_template.json to secrets.json and add real API keys
Use Skills - Skills are automatically available for specialized workflows (see AGENT.md for list)
Start coding! - Use claude "your task" to begin development

Template Version: 1.1.0 Last Updated: 2025-12-22 Questions? Open an issue at https://github.com/AutumnsGrove/BaseProject/issues

This file will be automatically deleted when you run setup.sh.

FilesExpand file tree

TEMPLATE_USAGE.md

Latest commit

History

TEMPLATE_USAGE.md

File metadata and controls

BaseProject Template - Complete Usage Guide

Table of Contents

Getting Started

Prerequisites

Two Ways to Use This Template

Option 1: GitHub Template (Recommended)

Option 2: Direct Clone

Quick Setup (Recommended)

What the Setup Script Does

Example Setup Session

Step-by-Step Manual Setup

1. Customize AGENT.md

2. Set Up Secrets Management

3. Initialize Your Language Environment

Python (with UV)

JavaScript/TypeScript

Go

Rust

4. Create Project Structure

5. Install Git Hooks (Optional but Recommended)

6. Update README.md

7. Create Initial TODOS.md

8. Clean Up Template Files

9. Initialize Git

Customization Guide

AGENT.md Customization

Project Purpose

Tech Stack

Architecture Notes

Secrets Configuration

AI/ML Projects

Cloud Projects

Web Services

Multi-Language Support

Python Projects

JavaScript/TypeScript Projects

Go Projects

Rust Projects

Multi-Language Projects

Feature Configuration

Git Hooks (Recommended)

Database Setup

Docker Support

CI/CD Workflows

File-by-File Explanation

Root Files

.claude/skills/ Directory (Skills)

AgentUsage/ Directory (Extended Reference)

AgentUsage/templates/

AgentUsage/pre_commit_hooks/

Troubleshooting

Setup Script Issues

"bash: setup.sh: Permission denied"

"UV not found" (Python projects)

"Git hooks installation failed"

Configuration Issues

"AGENT.md not updating"

"Secrets not loading"

"Git hooks not running"

Language-Specific Issues

Python: "Module not found"

JavaScript: "Cannot find module"

Go: "Package not found"

Git Issues

"Not a git repository"

"Author identity unknown"

Still Having Issues?

Next Steps After Setup