Skip to content

Instantly share code, notes, and snippets.

@watzon

watzon/setup.sh

Last active August 3, 2025 04:15
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save watzon/d362a7bea33e8fef21c9f9495cd9a331 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save watzon/d362a7bea33e8fef21c9f9495cd9a331 to your computer and use it in GitHub Desktop.
Download ZIP
Claude Infra Setup
Raw
setup.sh
#!/bin/bash
# Claude Code Infrastructure Setup Script with Research Functionality
# This script sets up a structured development environment with AI-powered workflow
echo "🚀 Claude Code Infrastructure Setup (with Research)"
echo "================================================"
# Create .claude directory structure
echo "📁 Creating .claude directory structure..."
mkdir -p .claude/{commands/{project,dev,task,emergency,git,research},templates,research,hooks}
# Create command files
echo "📝 Creating command files..."
# PROJECT COMMANDS
cat > .claude/commands/project/status.md << 'EOF'
# Project Status Overview
Display comprehensive project status including:
- Current task from TASKS.md
- Last checkpoint info
- Working state summary
- Recent commits
- File changes summary
Focus on actionable information for continuing work.
EOF
cat > .claude/commands/project/context.md << 'EOF'
# Load Full Project Context
1. Read CLAUDE.local.md completely
2. Load current sprint from TASKS.md
3. Check for .claude/session-state.md
4. Review recent SHIPPED.md entries
5. Display ready-to-work summary
Prepare to continue where last session ended.
EOF
# DEV COMMANDS
cat > .claude/commands/dev/start.md << 'EOF'
# Start New Development Task
1. Display current task from TASKS.md
2. Create branch: git checkout -b feature/[brief-name]
3. Display: "Ready to work on: [task]"
4. Reminder: Use /dev:checkpoint frequently
Set up clean workspace for focused development.
EOF
cat > .claude/commands/dev/checkpoint.md << 'EOF'
# Development Checkpoint
CRITICAL: Your #1 priority is preventing work loss!
1. First run: git add -A (stages ALL files including new ones)
2. Then run: git status (verify everything is staged)
3. Create checkpoint commit: git commit -m "checkpoint: [work-in-progress-description]"
4. Show what was saved
5. Update .claude/session-state.md with current progress
Why this matters:
- New files are NOT auto-staged by Git
- Without 'git add -A', work can be lost
- Checkpoints allow easy recovery
- Commit messages should describe WIP state
EOF
cat > .claude/commands/dev/ship.md << 'EOF'
# Ship Completed Work
Complete the current development cycle:
1. Run: git add -A (stage everything)
2. Run: git status (verify all changes staged)
3. Review changes: git diff --cached
4. Create commit: git commit -m "feat: [what-you-built]"
- Use conventional commits (feat/fix/docs/chore)
- NO self-attribution in commits
5. Update TASKS.md - mark items complete
6. Add entry to SHIPPED.md with feature and commit
7. Return to main: git checkout main
8. Fast-forward: git merge --ff-only feature/[branch]
9. Delete branch: git branch -d feature/[branch]
10. Clear .claude/session-state.md
Delivers clean, atomic features to main branch.
EOF
cat > .claude/commands/dev/diff.md << 'EOF'
# Show Current Changes
Display all changes in working directory:
1. Unstaged changes: git diff
2. Staged changes: git diff --cached
3. All changes from main: git diff main
4. File change summary: git status -s
Quick review of all current work.
EOF
cat > .claude/commands/dev/load-session.md << 'EOF'
# Load Previous Session
Restore context from last work session:
1. Read .claude/session-state.md if exists
2. Show current branch and last commit
3. Display working directory changes
4. Show current task from TASKS.md
5. Provide summary: "Ready to continue: [context]"
Enables seamless work continuation.
EOF
cat > .claude/commands/dev/next.md << 'EOF'
# Next Task
Show the next actionable task:
1. Read TASKS.md
2. Find first unchecked item in "Current Sprint"
3. Display task with any sub-items
4. Show related context if available
5. Suggest: "Use /task:breakdown if needed"
Quick task visibility for momentum.
EOF
# TASK COMMANDS
cat > .claude/commands/task/current.md << 'EOF'
# Current Task Status
Display current task context:
1. Show active task from TASKS.md
2. List completed sub-tasks
3. Show pending sub-tasks
4. Display any blockers
5. Related commits if any
Full visibility into task progress.
EOF
cat > .claude/commands/task/breakdown.md << 'EOF'
# Break Down Current Task
Decompose task into implementation steps:
1. Read current task from TASKS.md
2. Create 3-7 concrete sub-tasks
3. Each should be ~30min-2hr of work
4. Order by dependencies
5. Update TASKS.md with breakdown
6. Display the plan
Makes large tasks manageable.
EOF
cat > .claude/commands/task/add.md << 'EOF'
# Add New Task
Add task to appropriate section:
1. Parse task description from command
2. Determine sprint or backlog
3. Add to TASKS.md
4. Maintain priority order
5. Show updated task list
Keep task list current and organized.
EOF
cat > .claude/commands/task/complete.md << 'EOF'
# Complete Current Task
Mark task and subtasks as done:
1. Check off items in TASKS.md
2. Move to "Completed" if section exists
3. Create SHIPPED.md entry if shippable
4. Show next available task
5. Celebrate if appropriate!
Maintain momentum with clear progress.
EOF
# EMERGENCY COMMANDS
cat > .claude/commands/emergency/recover.md << 'EOF'
# Emergency Recovery
When things go wrong, get back on track:
1. Check git status - understand current state
2. If merge conflict: List files, show resolution steps
3. If detached HEAD: Explain state, provide fix
4. If uncommitted work: Create WIP checkpoint immediately
5. If bad commit: Show safe revert process
6. Update .claude/session-state.md with issues
Never lose work. Always recoverable.
EOF
cat > .claude/commands/emergency/abort.md << 'EOF'
# Abort Current Operation
Safely cancel in-progress work:
1. Assess current state (git status)
2. Stash changes if valuable: git stash -u
3. Abort merge/rebase/cherry-pick if active
4. Return to main branch
5. List stashed work if any
6. Provide recovery instructions
Clean escape hatch when needed.
EOF
# GIT COMMANDS
cat > .claude/commands/git/setup.md << 'EOF'
# Git Configuration
Set up Git for optimal workflow:
1. Configure user name/email if needed
2. Set up common aliases
3. Configure safety settings
4. Set default branch name
5. Enable auto-stash for rebase
One-time Git optimization.
EOF
cat > .claude/commands/git/history.md << 'EOF'
# Git History Summary
Show clean commit history:
1. Recent commits: git log --oneline -10
2. My commits today: git log --since="midnight"
3. Branch visualization if multiple branches
4. Highlight checkpoint vs feature commits
Understand project evolution.
EOF
cat > .claude/commands/git/undo.md << 'EOF'
# Undo Recent Changes
Safe ways to undo based on situation:
1. Uncommitted changes: Offer stash or reset
2. Last commit: Soft reset with explanation
3. Multiple commits: Interactive rebase guide
4. Pushed commits: Revert commit creation
Always preserve ability to recover.
EOF
cat > .claude/commands/git/safety-check.md << 'EOF'
# Git Safety Check
Verify repository health:
1. Check for uncommitted changes
2. Verify branch state
3. Check for untracked files
4. Ensure no merge conflicts
5. Verify remote sync status
Prevent issues before they happen.
EOF
# RESEARCH COMMANDS
cat > .claude/commands/research/new.md << 'EOF'
# Create New Research Document
Create a well-structured research document based on: $ARGUMENTS
## Research Protocol
### 1. Parse Research Request
Extract from $ARGUMENTS:
- Main topic/question
- Specific technologies or domains
- Desired depth (quick overview vs deep dive)
- Any specific code patterns needed
### 2. Create Research File
Create file in .claude/research/ with timestamp and topic:
```
.claude/research/YYYY-MM-DD-HH-MM-topic-name.md
```
### 3. Research File Format
```markdown
---
title: [Research Topic]
date: YYYY-MM-DD HH:MM
tags: [relevant, tags, here]
summary: |
One paragraph summary of the research topic and findings.
This should be 3-5 sentences that capture the essence.
key_findings:
- Finding 1
- Finding 2
- Finding 3
resources_used:
- Web Search
- Context7 MCP
- GitHub MCP
- Other sources
---
# [Research Topic]
## Executive Summary
[2-3 paragraphs summarizing the research]
## Research Findings
### Core Concepts
[Main concepts and definitions]
### Implementation Examples
[Code examples from GitHub and other sources]
### Best Practices
[Recommended approaches]
### Common Pitfalls
[Things to avoid]
## Code Examples
### Example 1: [Description]
```language
[code here]
```
Source: [GitHub repo or documentation]
### Example 2: [Description]
```language
[code here]
```
Source: [GitHub repo or documentation]
## Resources
### Documentation
- [Official docs](URL)
- [Tutorials](URL)
### GitHub Repositories
- [Repo 1](URL) - Description
- [Repo 2](URL) - Description
### Articles & Guides
- [Article 1](URL)
- [Article 2](URL)
## Recommendations
[Specific recommendations based on research]
## Further Research
[Topics that could be explored deeper]
```
### 4. Research Process
Use one or more **subagents** to do the following:
1. **Web Search**: Start with built-in search capabilities
- Search for official documentation
- Look for recent tutorials and guides
- Find community discussions
2. **Context7 MCP** (if available):
- Get official library documentation
- Find API references
- Get up-to-date examples
3. **GitHub MCP** (if available):
- Search for real-world implementations
- Find popular repositories using the technology
- Extract code patterns and best practices
- Look at issues for common problems
4. **Synthesis**:
- Combine findings from all sources
- Prioritize official sources
- Include practical examples
- Note version-specific information
### 5. Update Research Index
Maintain .claude/research/INDEX.md:
```markdown
# Research Index
## Recent Research
- [YYYY-MM-DD: Topic](./YYYY-MM-DD-HH-MM-topic-name.md) - Brief summary
## By Category
### Technology
- [Topic 1](link)
- [Topic 2](link)
### Patterns
- [Pattern 1](link)
- [Pattern 2](link)
```
### 6. Display Summary
After creating research:
```
✅ Research completed: [Topic]
📁 Saved to: .claude/research/YYYY-MM-DD-HH-MM-topic-name.md
🔍 Key findings:
- Finding 1
- Finding 2
- Finding 3
📚 Resources used: [list]
💡 See full research document for details and code examples
```
## Research Best Practices
- Always cite sources
- Include version numbers when relevant
- Prefer recent information (last 2 years)
- Include both simple and advanced examples
- Note licensing information for code
- Cross-reference with project requirements
EOF
cat > .claude/commands/research/list.md << 'EOF'
# List Research Documents
Display available research documents:
1. Read .claude/research/INDEX.md if exists
2. Otherwise scan .claude/research/ directory
3. Sort by date (newest first)
4. Show title, date, and summary for each
5. Group by category if applicable
Quick access to accumulated knowledge.
EOF
cat > .claude/commands/research/view.md << 'EOF'
# View Research Document
Display a specific research document: $ARGUMENTS
1. Parse filename or topic from arguments
2. Find matching research file
3. Display front matter summary first
4. Then show full document content
5. Highlight key findings and code examples
Access previous research quickly.
EOF
# Create template files
echo "📄 Creating template files..."
# Research index template
cat > .claude/research/INDEX.md << 'EOF'
# Research Index
## Recent Research
*No research documents yet. Use `/research:new [topic]` to create one.*
## By Category
*Categories will appear as you add research documents.*
## Quick Tips
- Research documents include front matter for quick scanning
- Each document contains code examples from real projects
- Sources are always cited for verification
- Use tags for easy categorization
EOF
# Create gitignore
cat > .gitignore << 'EOF'
# Claude Code Infrastructure
.claude/session-state.md
.claude/hooks/*.log
.claude/.env.local
CLAUDE.local.md
# Common
.env
.env.local
node_modules/
.DS_Store
*.log
dist/
build/
*.pyc
__pycache__/
.venv/
venv/
EOF
# Create initial CLAUDE.local.md
cat > CLAUDE.local.md << 'EOF'
# Project: [Your Project Name]
## 🔄 Session Continuity
**IMPORTANT**: Always check `.claude/session-state.md` when starting work!
## What It Does
[Brief description of what this project is/does]
## Quick Start
- Install: `[npm install / pip install -r requirements.txt / etc]`
- Run: `[npm run dev / python main.py / etc]`
- Test: `[npm test / pytest / etc]`
- Build: `[npm run build / etc]`
## Current Status
- Stage: [Planning/Development/Testing/Production]
- Priority: [Current focus area]
## Stack
- Language: [Primary language]
- Framework: [If applicable]
- Database: [If applicable]
- Key Dependencies: [List main ones]
## Project Structure
```
src/ # Main source code
tests/ # Test files
docs/ # Documentation
.claude/ # AI assistant infrastructure
```
## Git Workflow
1. Always checkpoint with: `/dev:checkpoint`
2. Ship completed work: `/dev:ship`
3. NO self-attribution in commits
4. Atomic commits with clear messages
## Development Commands
[Project-specific commands here]
## Architecture Notes
[Key architectural decisions and patterns]
## Known Issues & Solutions
[Document any project-specific gotchas]
## Lessons Learned
[This section is preserved across updates - document important discoveries]
- Date: Issue. Solution.
EOF
# Create initial TASKS.md
cat > TASKS.md << 'EOF'
# 📋 Task Management
## 🎯 Current Sprint (This Week)
- [ ] Set up initial project structure
- [ ] Initialize framework/language setup
- [ ] Create basic directory structure
- [ ] Set up development environment
- [ ] Configure build tools
- [ ] Implement core functionality
- [ ] (Use `/task:breakdown` when ready)
- [ ] Add basic documentation
- [ ] README with setup instructions
- [ ] Code comments for main functions
## 📦 Backlog (Later)
- [ ] Add comprehensive tests
- [ ] Set up CI/CD pipeline
- [ ] Add error handling
- [ ] Performance optimization
- [ ] Security review
## ✅ Completed
*Tasks moved here after shipping*
## 💡 Ideas & Notes
*Capture thoughts that aren't yet tasks*
---
Remember: Use `/dev:checkpoint` frequently and `/dev:ship` when done!
EOF
# Create SHIPPED.md
cat > SHIPPED.md << 'EOF'
# 🚀 Shipped Features
## Format
### ✅ Feature Name
- Shipped: YYYY-MM-DD
- Commit: [hash]
- Impact: What this enables/fixes
- Notes: Any important details
---
## Features
*No features shipped yet. They'll appear here after using `/dev:ship`*
---
## Quick Stats
- Total Features Shipped: 0
- Last Ship Date: Not yet
- Current Velocity: Building momentum!
EOF
# Create session state file (will be gitignored)
touch .claude/session-state.md
# Create hooks directory with README
cat > .claude/hooks/README.md << 'EOF'
# Git Hooks
This directory can contain project-specific Git hooks.
## Available Hooks
- pre-commit: Run before each commit
- post-commit: Run after each commit
- pre-push: Run before pushing
## Setup
Link these to your .git/hooks directory if needed:
```bash
ln -s ../../.claude/hooks/pre-commit .git/hooks/pre-commit
```
EOF
# Create sample pre-commit hook
cat > .claude/hooks/pre-commit << 'EOF'
#!/bin/bash
# Sample pre-commit hook - customize as needed
# Check for common issues
if git diff --cached --name-only | grep -q "\.env$"; then
echo "⚠️ Warning: .env file is staged for commit"
echo "Remove with: git reset HEAD .env"
exit 1
fi
# Add more checks as needed
EOF
chmod +x .claude/hooks/pre-commit
echo "✅ Claude Code infrastructure created successfully!"
echo ""
echo "📁 Created structure:"
echo " .claude/"
echo " ├── commands/ # All available commands"
echo " │ ├── project/ # Project management"
echo " │ ├── dev/ # Development workflow"
echo " │ ├── task/ # Task management"
echo " │ ├── emergency/ # Recovery commands"
echo " │ ├── git/ # Git utilities"
echo " │ └── research/ # Research documentation"
echo " ├── research/ # Research documents"
echo " ├── templates/ # Reusable templates"
echo " └── hooks/ # Git hooks"
echo ""
echo "📄 Created files:"
echo " - CLAUDE.local.md # Project configuration (customize this!)"
echo " - TASKS.md # Task tracking"
echo " - SHIPPED.md # Feature delivery log"
echo " - .gitignore # Ignore rules"
echo ""
echo "🚀 Next steps:"
echo " 1. Edit CLAUDE.local.md with your project details"
echo " 2. Update TASKS.md with your specific tasks"
echo " 3. Start work with: /dev:start"
echo " 4. Create research: /research:new [topic]"
echo ""
echo "⚠️ Remember: ALWAYS use /dev:checkpoint to save work!"
EOF
# Make script executable
chmod +x setup-with-research.sh
echo "✅ Modified setup script created: setup-with-research.sh"
echo ""
echo "📋 Changes made:"
echo " - Added research/ directory to .claude/"
echo " - Created research command structure:"
echo " • /research:new - Create new research document"
echo " • /research:list - List all research"
echo " • /research:view - View specific research"
echo " - Defined research file format with front matter"
echo " - Added research index template"
echo " - Included instructions for using:"
echo " • Built-in web search"
echo " • Context7 MCP server"
echo " • GitHub MCP server"
echo ""
echo "🔍 Research documents will:"
echo " - Be stored in .claude/research/"
echo " - Use YYYY-MM-DD-HH-MM-topic-name.md format"
echo " - Include structured front matter for quick scanning"
echo " - Contain code examples from GitHub"
echo " - Cite all sources"
echo " - Be indexed for easy retrieval"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment