Quick Start: Click the green button above β Clone your new repo β Run bash setup.sh
A comprehensive project template with built-in Claude Code workflows, best practices, and extensive documentation for rapid development setup.
What you get: Git hooks β’ Multi-language support β’ Security defaults β’ 18 comprehensive guides β’ Claude-optimized workflows
Copy this prompt into Claude Code:
I want to create a new project from the BaseProject template. Follow this workflow:
1. First, ask me for: project name, description, tech stack (Python/JS/Go), and what API keys I'll need
2. Clone https://github.com/AutumnsGrove/BaseProject (main branch) to /tmp
3. Copy to ~/Projects/[PROJECT_NAME] (exclude .git/)
4. Copy .claude/skills/ folder (Claude Code Skills are the primary workflow mechanism)
5. Customize AGENT.md with my project details (Purpose, Tech Stack, Architecture)
6. Update README.md with project-specific info (title, description, features)
7. Init language dependencies (uv init for Python, pnpm init for JS, go mod init for Go)
8. Create directory structure: src/ and tests/ with proper init files for the chosen language
9. Generate secrets_template.json with my API key placeholders
10. Create TODOS.md with 3-5 starter tasks based on the project description
11. Run git init using global git config (user.name and user.email)
12. Ask if I want to install git hooks (recommended: yes, auto-detects language from files created in step 7)
13. If yes, run ./AgentUsage/pre_commit_hooks/install_hooks.sh
14. Ask if I want to install house-agents (recommended: yes, includes house-coder and house-planner)
15. If yes, check if ~/.claude/agents/house-research.md exists; if not, clone https://github.com/AutumnsGrove/house-agents.git and copy agents to ~/.claude/agents/
16. Make initial commit: "feat: initialize [PROJECT] from BaseProject template"
17. Display project summary including available skills and next steps
Start by asking me for the project details.
Claude will interactively:
- Ask for project name, tech stack, and requirements
- Copy BaseProject template to your chosen location
- Install Claude Code Skills - the primary mechanism for specialized workflows
- Customize AGENT.md with your project details
- Set up language-specific dependencies (pyproject.toml, package.json, etc.)
- Create proper project structure (src/, tests/)
- Generate secrets_template.json with your needed API keys
- Initialize git with proper configuration
- Install git hooks (recommended) - auto-detects your language and installs:
- Code quality checks (Black/Ruff for Python, Prettier/ESLint for JS, gofmt for Go)
- Security scanner (prevents committing API keys/secrets)
- Test runner (blocks push if tests fail)
- Dependency auto-updater (runs on branch switch)
- Install house-agents (recommended) - includes all 5 specialized agents:
- house-research, house-git, house-bash (from upstream)
- house-coder, house-planner (from AutumnsGrove fork)
- Skips if agents already installed
- Create initial commit following our standards
Copy this prompt into Claude Code (run in your project directory):
I want to add BaseProject structure to my CURRENT project. Follow this workflow:
1. Analyze my existing project: read README.md, AGENT.md, git history for commit patterns, detect tech stack and package managers, identify architecture (monorepo/single/etc), read TODOS.md if exists
2. Clone https://github.com/AutumnsGrove/BaseProject (main branch) to /tmp/bp
3. Copy .claude/skills/ folder to my project (Claude Code Skills are the primary workflow mechanism)
4. Copy AgentUsage/ to my project (preserve any existing AgentUsage/ files, only add new guides - these serve as extended reference)
5. Intelligently merge AGENT.md: if exists, parse sections and merge BaseProject sections using markers like "<!-- BaseProject: Git Workflow -->". If doesn't exist, create from template with detected project details. Ensure skills usage instructions are included.
6. Enhance .gitignore by merging entries (preserve existing, add missing from BaseProject)
7. Analyze commit messages and suggest adopting BaseProject conventional commit style if inconsistent
8. Check if using branches like dev/main and suggest workflow if not
9. Ask if I want to install git hooks (they auto-detect my language and back up existing hooks first)
10. If yes, run ./AgentUsage/pre_commit_hooks/install_hooks.sh interactively
11. Ask if I want to install house-agents (includes house-coder and house-planner for enhanced workflows)
12. If yes, check if ~/.claude/agents/house-research.md exists; if not, clone https://github.com/AutumnsGrove/house-agents.git and copy agents to ~/.claude/agents/
13. Generate/update TODOS.md with project-aware tasks
14. Create integration-summary.md report showing what was added/merged/skipped (including skills list)
15. Backup all modified files to ./.baseproject-backup-[TIMESTAMP]/
16. Cleanup /tmp/bp
17. Display next steps including available skills
Start by analyzing my current project.
Claude will intelligently:
- Analyze your existing project structure and conventions
- Detect tech stack from package files (package.json, pyproject.toml, etc.)
- Install Claude Code Skills - the primary mechanism for specialized workflows
- Copy AgentUsage/ guides without overwriting existing files (extended reference docs)
- Merge AGENT.md sections with clear markers (preserves your content, adds skills instructions)
- Append missing .gitignore entries without removing existing ones
- Compare your commit style to BaseProject standards and offer suggestions
- Optionally install git hooks - backs up existing hooks, auto-detects language, installs appropriate quality/security hooks
- Optionally install house-agents - includes house-coder and house-planner, skips if already installed
- Create backup of all modified files before making changes
- Generate integration-summary.md showing exactly what was changed (including available skills)
- Respect your existing README.md (won't overwrite)
- Adapt to your project's existing structure
Already using BaseProject? Keep your AgentUsage docs and hooks up to date!
This option is for projects that already have BaseProject installed and want to sync with the latest updates.
Quick Update (Automated Script):
# In your project directory
curl -sSL https://raw.githubusercontent.com/AutumnsGrove/BaseProject/main/update_baseproject.sh | bash
# OR if you have BaseProject cloned locally:
bash /path/to/BaseProject/update_baseproject.shWhat the Update Script Does:
-
Detects and migrates old folders:
- Finds old
ClaudeUsagefolders and migrates them toAgentUsage - Backs up everything before making changes
- Finds old
-
Syncs Claude Code Skills (Primary):
- Updates all skills in
.claude/skills/with latest versions - Skills are the primary mechanism for specialized workflows
- Lists all available skills after sync
- Updates all skills in
-
Syncs AgentUsage folder (Extended Reference):
- Updates all documentation guides with latest versions
- Refreshes git hooks with newest implementations
- Updates templates and examples
- Shows detailed summary of added/updated/unchanged files
-
Merges .gitignore entries:
- Adds new patterns from BaseProject
- Preserves all your existing entries
-
Preserves your customizations:
- β
Keeps your
AGENT.md(project instructions) - β
Keeps your
README.md(project documentation) - β
Keeps your
TODOS.md(task list) - β
Keeps your
secrets.jsonandsecrets_template.json - β Keeps all language-specific files (pyproject.toml, package.json, etc.)
- β Keeps all your source code
- β
Keeps your
-
Provides update summary:
- Creates
baseproject-update-summary.mdwith detailed changes - Lists available skills and their purposes
- Creates backup in
.baseproject-backup-[TIMESTAMP]/ - Shows exactly what was changed and why
- Creates
Manual Update (via Claude Code):
I want to update my BaseProject installation. Follow this workflow:
1. Check current directory for existing .claude/skills/, AgentUsage, or old ClaudeUsage folders
2. Clone https://github.com/AutumnsGrove/BaseProject (main branch) to /tmp/bp-update
3. Create backup of existing files to .baseproject-backup-[TIMESTAMP]/
4. If ClaudeUsage folder exists:
- Back it up to .baseproject-backup-[TIMESTAMP]/
- Migrate contents to AgentUsage (preserve custom files, merge intelligently)
5. Sync .claude/skills/ folder from BaseProject (Skills are the PRIMARY workflow mechanism):
- Compare each file (add new, update changed, preserve unchanged)
- Show summary of added/updated/unchanged skills
- List all available skills after sync
6. Sync AgentUsage folder from BaseProject (Extended reference docs):
- Compare each file (add new, update changed, preserve unchanged)
- Show summary of added/updated/unchanged files
- Keep any custom guides I've added
7. Update .gitignore by merging new entries (don't remove my existing entries)
8. Ask if I want to reinstall git hooks with latest versions
9. If yes, run ./AgentUsage/pre_commit_hooks/install_hooks.sh
10. Generate baseproject-update-summary.md report showing all changes including available skills
11. DO NOT touch: AGENT.md, README.md, TODOS.md, secrets files, language configs, source code
12. Cleanup phase:
- Delete old ClaudeUsage folder (if it was migrated)
- Cleanup /tmp/bp-update
13. Commit the updates with message "chore: sync BaseProject skills and docs" (do NOT include baseproject-update-summary.md in the commit - only commit the actual file changes)
14. Display summary including available skills and next steps
Start the update process.
When to Use This Option:
- β Your project already has BaseProject installed (AgentUsage folder exists)
- β You want to get the latest documentation guides and git hooks
- β You're migrating from old "ClaudeUsage" naming to "AgentUsage"
- β You want to keep your project setup but refresh the docs
Example Output:
$ bash update_baseproject.sh
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β BaseProject Update/Sync Tool β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Checking for Old Folders
βββββββββββββββββββββββββ
β Found old 'ClaudeUsage' folder
β Backed up ClaudeUsage to .baseproject-backup-20251119-143500/
β Renamed ClaudeUsage β AgentUsage
Syncing Claude Code Skills
βββββββββββββββββββββββββββ
β Added: research-strategy/SKILL.md
β Updated: database-management/SKILL.md
Skills Sync Summary:
β Added: 2 files
β Updated: 3 files
βΉ Unchanged: 13 files
Available skills:
β’ api-integration
β’ database-management
β’ git-workflows
β’ python-testing
β’ secrets-management
... (18 total)
Syncing AgentUsage Folder
ββββββββββββββββββββββββββ
β Added: house_agents.md
β Updated: git_guide.md
Sync Summary:
β Added: 3 files
β Updated: 8 files
βΉ Unchanged: 12 files
Updating .gitignore
βββββββββββββββββββ
β Added 4 new entries to .gitignore
Update Complete!
ββββββββββββββββ
β Skills folder synced with latest BaseProject
β AgentUsage folder synced with latest BaseProject
β Backup saved to: .baseproject-backup-20251119-143500/
β Update summary: baseproject-update-summary.mdAlready copied your project files in but still have all the template scaffolding? Use this!
This is for when you've imported your existing project content (specs, license, scripts, tools, etc.) but the BaseProject template files (AGENT.md, README.md, TODOS.md) still have placeholder text.
Copy this prompt into Claude Code:
I've imported my project content into the BaseProject template, but the template files still have placeholders. Analyze everything and build out the project properly. Follow this workflow:
1. Deep Analysis Phase:
- Read ALL files in the project to understand what exists
- Identify: project specs, documentation, licenses, scripts, tools, configs
- Detect tech stack from existing files (package.json, pyproject.toml, go.mod, etc.)
- Map the current file structure and identify what belongs where
- Note any existing README, SPEC, or documentation files that should replace template placeholders
2. Create Reorganization Plan:
- Propose a clean directory structure based on what you found
- Plan where specs/docs should live (e.g., move SPEC.md to docs/)
- Identify which template files to replace vs. populate
- List all files that will be created, moved, or modified
- Present the plan and ask for confirmation before proceeding
3. Execute the Plan (after confirmation):
- Create necessary directories (src/, docs/, tests/, etc.)
- Move/reorganize files according to the plan
- Update all file path references in moved files
- Replace template AGENT.md with real project details extracted from specs
- Replace template README.md with project-appropriate content
- Generate TODOS.md with actual next steps based on project state
- Update .gitignore for the detected tech stack
- Create any missing standard files (LICENSE, CONTRIBUTING.md, etc. if content exists)
4. Cross-Reference & Validation:
- Verify all internal links/references are updated
- Check for orphaned files or broken references
- Ensure no duplicate documentation exists
- Validate directory structure matches tech stack conventions
5. Finalize:
- Initialize/update language dependencies if needed
- Offer to install git hooks appropriate for detected tech stack
- Create initial commit with message "feat: scaffold project from imported content"
- Display summary of changes: files created, moved, modified, deleted
- List recommended next steps
Start by reading everything in the project directory.
Claude will:
- Discover your project by reading all imported files
- Understand specs, docs, scripts, and architecture from what you've brought in
- Create a tailored reorganization plan (asks for approval first)
- Move files to proper locations (specs β docs/, source β src/, etc.)
- Update all references in moved files so nothing breaks
- Transform template placeholders into real project documentation
- Generate actionable TODOS.md based on actual project state
- Set up proper structure for your detected tech stack
- Optionally install appropriate git hooks
When to Use This Option:
- β You copied an existing project into the BaseProject template
- β Template files (AGENT.md, README.md) still have placeholder text
- β You have specs, licenses, scripts, or tools that need proper organization
- β You want Claude to figure out the structure from what's there
- β Files need to be reorganized (e.g., SPEC.md should move to docs/)
Example Scenario:
Your imported content:
βββ SPEC.md # Full project specification
βββ my-tool.py # Main script
βββ LICENSE # Your real license
βββ ProjectReadme.md # Your actual readme (not the template one)
βββ config.yaml # Project config
βββ AGENT.md # β Still has template placeholders
βββ README.md # β Still the template README
βββ AgentUsage/ # Template guides
After running the prompt:
βββ docs/
β βββ SPEC.md # Moved, references updated
βββ src/
β βββ my-tool.py # Organized into src/
βββ config.yaml
βββ LICENSE
βββ AGENT.md # β Populated with real project details from SPEC
βββ README.md # β Replaced with ProjectReadme.md content + enhancements
βββ TODOS.md # β Generated from actual project state
βββ AgentUsage/
βββ pyproject.toml # Created for detected Python project
For full control over the setup process, see TEMPLATE_USAGE.md for detailed step-by-step instructions.
BaseProject/
βββ CLAUDE.md # Redirect to AGENT.md
βββ AGENT.md # Main project instructions file
βββ .claude/
β βββ skills/ # Claude Code Skills (PRIMARY workflow mechanism)
β βββ secrets-management/ # API keys, credentials
β βββ database-management/# SQLite, database.py patterns
β βββ git-workflows/ # Commits, branching
β βββ python-testing/ # pytest patterns
β βββ ... (18 total skills)
βββ AgentUsage/ # Extended reference documentation
β βββ README.md # Guide index with skill mapping
β βββ git_guide.md # Detailed git workflow
β βββ db_usage.md # Complete database patterns
β βββ secrets_management.md # Advanced API key handling
β βββ pre_commit_hooks/ # Git hooks for code quality
β βββ templates/ # Template files for common configs
β βββ ... (25 total guides)
βββ .gitignore # Comprehensive gitignore
Skills vs AgentUsage:
- Skills (
.claude/skills/) - Primary mechanism, concise and actionable, invoke via Skill tool - AgentUsage - Extended reference for when you need more detail than skills provide
This template works seamlessly with house-agents - specialized Claude Code sub-agents that keep your context clean.
Specialized sub-agents that run heavy operations in separate context windows:
- house-research - Search 70k+ tokens across files, return 3k summary (95% savings)
- house-git - Analyze 43k token diffs, return 500 token summary (98% savings)
- house-bash - Process 21k+ command output, return 700 token summary (97% savings)
- house-coder - Small code patches (0-250 lines), instant TODO implementations
- house-planner - Task orchestration & planning for multi-file changes
Project-Level (this project only):
# Clone the fork with house-coder and house-planner agents
git clone https://github.com/AutumnsGrove/house-agents.git /tmp/house-agents
cp -r /tmp/house-agents/.claude .User-Wide (all projects):
# Clone the fork with house-coder and house-planner agents
git clone https://github.com/AutumnsGrove/house-agents.git /tmp/house-agents
mkdir -p ~/.claude/agents
# Skip if agents already exist, otherwise copy them
if [ ! -f ~/.claude/agents/house-research.md ]; then
cp /tmp/house-agents/.claude/agents/*.md ~/.claude/agents/
echo "House agents installed successfully!"
else
echo "House agents already exist, skipping installation"
fiTest Installation:
Use house-research to find all TODO comments in the codebase
See AgentUsage/house_agents.md for usage patterns and examples.
Credit: House Agents originally by @houseworthe, enhanced fork with house-coder and house-planner by @AutumnsGrove
For additional Claude Code hooks and advanced git automation, check out Hooks - a comprehensive collection of productivity-enhancing hooks:
Key Features:
- Comprehensive automation toolkit - Claude Code event hooks (PreToolUse, PostToolUse, UserPromptSubmit) plus Git pre-commit hooks with auto-language detection
- Built-in security safeguards - Pre-commit secrets scanner blocks 15+ secret patterns (Anthropic, OpenAI, AWS, GitHub, etc.) with remediation guidance
- Cross-machine sync - Git-based hook management for easy deployment across multiple development environments
Quick Install:
git clone https://github.com/AutumnsGrove/Hooks.git ~/.claude/hooks-collection
# Follow repo README for specific hook installationThis pairs perfectly with BaseProject's built-in git hooks for a complete automation setup.
- Git workflow patterns - Conventional commits, unified git guide
- Database architecture - SQLite with isolated database.py interface
- Security by default - API key management, secrets scanning hooks
- Code quality hooks - 8 production-ready git hooks for Python, JS, Go, multi-language
pre-commit-secrets-scanner- Prevents committing API keys (15+ patterns)- Language-specific formatters (Black, Prettier, gofmt) and linters
- Auto-run tests before push, auto-update deps on branch switch
- Interactive installer with auto-detection
- Testing strategies - Unit, integration, and E2E test patterns
- CI/CD templates - GitHub Actions workflows
- Documentation standards - Consistent, scannable docs
- House agents - Specialized agents for research, coding, git analysis
- Context7 integration - Automatic library documentation fetching
- TODO management - Task tracking integrated into workflow
- Subagent patterns - Breaking down complex tasks
Guides and patterns for:
- Python (with UV package manager)
- JavaScript/TypeScript
- Go
- Rust
- Docker containerization
All guides follow a consistent, scannable format:
- Overview - What the guide covers
- When to Use - Specific triggers and scenarios
- Core Concepts - Key principles
- Practical Examples - Real-world code
- Common Pitfalls - What to avoid
- Related Guides - Cross-references
See AgentUsage/README.md for the complete index.
After running setup:
-
Edit AGENT.md - Fill in your project specifics
- Project purpose
- Tech stack
- Architecture notes
-
Create secrets files (if needed)
# For Python projects cp AgentUsage/templates/secrets_template.json secrets_template.json cp secrets_template.json secrets.json # Edit secrets.json with real API keys
-
Set up dependencies
# Python with UV uv init # JavaScript/Node pnpm init # Go go mod init yourproject
-
Install git hooks (recommended)
# Interactive installer (auto-detects your language) ./AgentUsage/pre_commit_hooks/install_hooks.sh # This installs: # - Code quality checks (formatters + linters) # - Security scanner (prevents API key leaks) # - Test runner (blocks push if tests fail) # - Dependency auto-updater
-
Update TODOS.md - Add your specific tasks
- Check
TODOS.mdfor pending tasks - Use Context7 to fetch relevant library docs
- Follow git workflow for commits
- Update TODOS.md as you progress
- Read
AgentUsage/secrets_management.md - Create
secrets.json(gitignored) - Provide
secrets_template.jsonfor team - Use environment variable fallbacks
- Use house-research agent for 20+ file searches
- Check
AgentUsage/house_agents.mdfor patterns - Use subagents for complex multi-step tasks
- Review
AgentUsage/testing_strategies.md - Follow framework-specific patterns
- Use test-strategist agent for planning
This template includes security best practices by default:
- β
secrets.jsonin.gitignore - β
Pre-commit secrets scanner - Detects 15+ secret patterns before commit
- Anthropic, OpenAI, AWS, GitHub, Google API keys
- JWT tokens, bearer tokens, private keys
- Hardcoded passwords and database credentials
- Actionable fix instructions when secrets detected
- β Environment variable fallback patterns
- β
Security audit guides in
secrets_advanced.md
This template is optimized for Claude Code CLI. Key features:
- AGENT.md contains all project instructions (read via CLAUDE.md redirect)
- Structured guides for quick reference without token bloat
- Subagent workflows for complex tasks
- Git commit standards with auto-formatting
cd ~/Projects/MyNewProject/
# Claude automatically reads CLAUDE.md β AGENT.md and knows your project context
claude "Add user authentication with JWT tokens"
# Claude will:
# 1. Check TODOS.md
# 2. Use Context7 to fetch JWT library docs
# 3. Implement following your git commit standards
# 4. Update TODOS.md
# 5. Commit with proper message formatRecommended reading order for new projects:
- project_structure.md - Directory layouts
- git_guide.md - Version control and conventional commits
- db_usage.md - Database setup (if using databases)
- secrets_management.md - API keys
- uv_usage.md - Python dependencies (if applicable)
- testing_strategies.md - Test setup
- house_agents.md - Advanced workflows
git init
git add .
git commit -m "Initial commit"If you see this error, the setup script may not have run properly. Make sure you've run bash setup.sh in your project directory.
chmod +x AgentUsage/pre_commit_hooks/*
./AgentUsage/pre_commit_hooks/install_hooks.shSee AgentUsage/pre_commit_hooks/TROUBLESHOOTING.md for comprehensive hook troubleshooting.
To get updates from BaseProject while preserving your customizations, use the automated update script (see Option 3 above):
# Recommended: Use the update script
bash update_baseproject.sh
# OR download and run directly:
curl -sSL https://raw.githubusercontent.com/AutumnsGrove/BaseProject/main/update_baseproject.sh | bashWhat gets updated:
- β .claude/skills/ folder (Claude Code Skills - primary mechanism)
- β AgentUsage/ guides and documentation (extended reference)
- β Git hooks in AgentUsage/pre_commit_hooks/
- β .gitignore entries (merged, not replaced)
What stays unchanged:
- β Your AGENT.md, README.md, TODOS.md
- β Your secrets files
- β Your source code and configs
Manual update (for specific files only):
# Copy a specific skill
cp -r /path/to/BaseProject/.claude/skills/new-skill .claude/skills/
# Copy a specific guide
cp /path/to/BaseProject/AgentUsage/new_guide.md AgentUsage/
# Review and commit
git diff .claude/skills/ AgentUsage/
git add .claude/skills/ AgentUsage/
git commit -m "chore: update BaseProject skills and guides"After setup:
- Customize - Edit AGENT.md with your project details
- Use Skills - Skills are automatically available for specialized workflows (see AGENT.md for list)
- Build - Start coding with Claude Code
- Iterate - Update TODOS.md as needed
Found a better pattern? Want to add a guide?
This template uses a two-branch strategy:
mainbranch - Clean, user-facing template (you're here)devbranch - Template development and maintenance
- Check out the dev branch
- Read CONTRIBUTING.md for full workflow
- Make changes in dev branch
- Test thoroughly before merging to main
- Add your guide to
AgentUsage/ - Update
AgentUsage/README.mdindex - Follow the documentation standards in
AgentUsage/documentation_standards.md - Commit with proper message format
This template is provided as-is for use with Claude Code. Customize freely for your projects.
Last updated: 2025-12-22 Maintained for: Claude Code CLI Skills: 18 Claude Code Skills | Guides: 25 extended reference documents