426 lines
11 KiB
Markdown
426 lines
11 KiB
Markdown
---
|
|
name: setup
|
|
description: Interactive setup wizard - analyzes tech stack, generates PROJECT.md, configures hooks
|
|
argument_hint: "[--project-dir <path>]"
|
|
allowed-tools: [Task, Read, Write, Bash, Grep, Glob]
|
|
---
|
|
|
|
# /setup - Project Initialization Wizard
|
|
|
|
**Purpose**: Initialize autonomous-dev in a project with intelligent PROJECT.md generation.
|
|
|
|
**Core Value**: Analyzes your codebase and generates comprehensive PROJECT.md (brownfield) or guides you through creation (greenfield).
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
/setup
|
|
```
|
|
|
|
**Time**: 2-5 minutes
|
|
**Interactive**: Yes (guides you through choices)
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
### Step 1: Install Plugin Files
|
|
|
|
```bash
|
|
# Delegate to sync_dispatcher for reliable file installation
|
|
echo "Installing plugin files..."
|
|
python3 .claude/lib/sync_dispatcher.py --github
|
|
|
|
# Fallback if .claude/lib doesn't exist yet (fresh install)
|
|
if [ $? -ne 0 ]; then
|
|
# Try from plugins/ directory (dev environment)
|
|
python3 plugins/autonomous-dev/lib/sync_dispatcher.py --github
|
|
fi
|
|
```
|
|
|
|
**What this does**:
|
|
- Downloads latest files from GitHub
|
|
- Copies to `.claude/` directory
|
|
- Validates all paths for security
|
|
- Non-destructive (preserves existing PROJECT.md, .env)
|
|
|
|
**If sync fails**: Show error and suggest manual sync with `/sync --github`
|
|
|
|
---
|
|
|
|
### Step 1.5: Create .env Configuration
|
|
|
|
After plugin files are installed, create `.env` from template:
|
|
|
|
```bash
|
|
# Check if .env already exists
|
|
if [ ! -f ".env" ]; then
|
|
# Copy from .env.example if it exists (standard convention)
|
|
if [ -f ".env.example" ]; then
|
|
cp .env.example .env
|
|
echo "Created .env from .env.example"
|
|
else
|
|
# Create minimal .env with essential settings
|
|
cat > .env << 'ENVEOF'
|
|
# autonomous-dev Environment Configuration
|
|
# See: https://github.com/akaszubski/autonomous-dev#environment-setup
|
|
|
|
# =============================================================================
|
|
# API KEYS (REQUIRED - fill these in!)
|
|
# =============================================================================
|
|
GITHUB_TOKEN=ghp_your_token_here
|
|
# ANTHROPIC_API_KEY=sk-ant-your_key_here
|
|
|
|
# =============================================================================
|
|
# GIT AUTOMATION (enabled by default)
|
|
# =============================================================================
|
|
AUTO_GIT_ENABLED=true
|
|
AUTO_GIT_PUSH=true
|
|
AUTO_GIT_PR=false
|
|
|
|
# =============================================================================
|
|
# TOOL AUTO-APPROVAL (reduces permission prompts)
|
|
# =============================================================================
|
|
MCP_AUTO_APPROVE=true
|
|
|
|
# =============================================================================
|
|
# BATCH PROCESSING
|
|
# =============================================================================
|
|
BATCH_RETRY_ENABLED=true
|
|
ENVEOF
|
|
echo "Created .env with default settings"
|
|
fi
|
|
fi
|
|
|
|
# Ensure .env is in .gitignore
|
|
if [ -f ".gitignore" ]; then
|
|
if ! grep -q "^\.env$" .gitignore; then
|
|
echo ".env" >> .gitignore
|
|
echo "Added .env to .gitignore"
|
|
fi
|
|
else
|
|
echo ".env" > .gitignore
|
|
echo "Created .gitignore with .env"
|
|
fi
|
|
```
|
|
|
|
**After creating .env, ALWAYS prompt the user:**
|
|
|
|
```
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
⚠️ ACTION REQUIRED: Configure your .env file
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
A .env file has been created with default settings. You MUST update the
|
|
API keys and tokens for full functionality.
|
|
|
|
Required (at minimum):
|
|
GITHUB_TOKEN=ghp_your_token_here
|
|
→ Create at: https://github.com/settings/tokens
|
|
→ Scopes needed: repo, read:org
|
|
|
|
Optional but recommended:
|
|
ANTHROPIC_API_KEY=sk-ant-your_key_here
|
|
→ Get from: https://console.anthropic.com/
|
|
→ Enables: GenAI security scanning, test generation, doc fixes
|
|
|
|
Key settings already enabled:
|
|
AUTO_GIT_ENABLED=true (auto-commit after /auto-implement)
|
|
AUTO_GIT_PUSH=true (auto-push commits)
|
|
MCP_AUTO_APPROVE=true (reduce permission prompts)
|
|
BATCH_RETRY_ENABLED=true (retry transient failures)
|
|
|
|
Edit .env now:
|
|
vim .env
|
|
# or
|
|
code .env
|
|
|
|
See all options: cat .env (file is fully documented)
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
```
|
|
|
|
**Wait for user confirmation before continuing to Step 2.**
|
|
|
|
---
|
|
|
|
### Step 2: Detect Project Type
|
|
|
|
After files installed, invoke the **setup-wizard** agent with this context:
|
|
|
|
```
|
|
CONTEXT FOR SETUP-WIZARD:
|
|
|
|
Step 1 (file installation) is COMPLETE. Files are in .claude/
|
|
|
|
Your job now is:
|
|
1. Detect if this is a BROWNFIELD (existing code) or GREENFIELD (new project)
|
|
2. Generate or help create PROJECT.md
|
|
3. Optionally configure hooks
|
|
4. Validate the setup
|
|
|
|
DETECTION RULES:
|
|
- BROWNFIELD: Has README.md, src/, package.json, pyproject.toml, or >10 source files
|
|
- GREENFIELD: Empty or near-empty project
|
|
|
|
For BROWNFIELD:
|
|
- Analyze: README.md, package.json/pyproject.toml, directory structure, git history
|
|
- Generate: Comprehensive PROJECT.md (80-90% complete)
|
|
- Mark TODOs: Only for CONSTRAINTS and CURRENT SPRINT (user must define)
|
|
|
|
For GREENFIELD:
|
|
- Ask: Primary goal, architecture type, tech stack
|
|
- Generate: PROJECT.md template with user inputs filled in
|
|
- Mark TODOs: More sections need user input
|
|
|
|
Then:
|
|
- Offer hook configuration (automatic vs manual workflow)
|
|
- Run health check to validate
|
|
- Show next steps
|
|
```
|
|
|
|
---
|
|
|
|
## What Gets Created
|
|
|
|
### Always Created
|
|
|
|
**Directory**: `.claude/`
|
|
- `agents/` - 20 AI agents
|
|
- `commands/` - 7 slash commands
|
|
- `hooks/` - 13 core automation hooks
|
|
- `lib/` - 35 Python libraries
|
|
- `skills/` - 28 skill packages
|
|
|
|
### PROJECT.md Generation
|
|
|
|
**Brownfield** (existing project):
|
|
```markdown
|
|
# Auto-generated sections (from codebase analysis):
|
|
- Project Vision (from README.md)
|
|
- Goals (from README roadmap/features)
|
|
- Architecture (detected from structure)
|
|
- Tech Stack (detected from package files)
|
|
- File Organization (detected patterns)
|
|
- Testing Strategy (detected from tests/)
|
|
- Documentation Map (detected from docs/)
|
|
|
|
# TODO sections (user must fill):
|
|
- CONSTRAINTS (performance, scale limits)
|
|
- CURRENT SPRINT (active work)
|
|
```
|
|
|
|
**Greenfield** (new project):
|
|
```markdown
|
|
# Generated from user responses:
|
|
- Project Vision
|
|
- Goals (based on primary goal selection)
|
|
- Architecture (based on architecture choice)
|
|
|
|
# TODO sections (more user input needed):
|
|
- SCOPE (in/out of scope)
|
|
- CONSTRAINTS
|
|
- CURRENT SPRINT
|
|
- File Organization
|
|
```
|
|
|
|
### Optional: Hook Configuration
|
|
|
|
**Manual Mode** (default):
|
|
- No additional config needed
|
|
- User runs formatting and testing tools manually
|
|
|
|
**Automatic Hooks Mode**:
|
|
- Hooks are configured automatically in settings.local.json
|
|
- Post-edit formatting via unified_post_tool.py
|
|
- Pre-tool-use validation via unified_pre_tool.py
|
|
- See `.claude/settings.local.json` for full hook configuration
|
|
|
|
---
|
|
|
|
## Example Flow
|
|
|
|
### Brownfield Project (existing code)
|
|
|
|
```
|
|
/setup
|
|
|
|
Step 1: Installing plugin files...
|
|
✓ Synced 47 files from GitHub
|
|
|
|
Step 2: Detecting project type...
|
|
✓ BROWNFIELD detected (Python project with 213 commits)
|
|
|
|
Analyzing codebase...
|
|
✓ Found README.md (extracting vision)
|
|
✓ Found pyproject.toml (Python 3.11, FastAPI)
|
|
✓ Analyzing src/ (47 files, layered architecture)
|
|
✓ Analyzing tests/ (unit + integration)
|
|
✓ Analyzing git history (TDD workflow detected)
|
|
|
|
Generating PROJECT.md...
|
|
✓ Created PROJECT.md at root (412 lines, 95% complete)
|
|
|
|
Sections auto-generated:
|
|
✓ Project Vision
|
|
✓ Goals (from README)
|
|
✓ Architecture (Layered API pattern)
|
|
✓ Tech Stack (Python, FastAPI, PostgreSQL)
|
|
✓ File Organization
|
|
✓ Testing Strategy
|
|
|
|
Sections needing your input:
|
|
📝 CONSTRAINTS - Define performance/scale limits
|
|
📝 CURRENT SPRINT - Define active work
|
|
|
|
Step 3: Hook configuration
|
|
How would you like to run quality checks?
|
|
[1] Slash Commands (manual control - recommended for beginners)
|
|
[2] Automatic Hooks (auto-format, auto-test)
|
|
> 1
|
|
|
|
✓ Slash commands mode selected (no additional config)
|
|
|
|
Step 4: Validation
|
|
Running health check...
|
|
✓ 20/20 agents loaded
|
|
✓ 13/13 hooks executable
|
|
✓ 7/7 commands present
|
|
✓ PROJECT.md exists
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
✓ Setup Complete!
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
Next steps:
|
|
1. Review PROJECT.md and fill in TODO sections
|
|
2. Try: /auto-implement "add a simple feature"
|
|
3. When done: /clear (reset context for next feature)
|
|
```
|
|
|
|
### Greenfield Project (new/empty)
|
|
|
|
```
|
|
/setup
|
|
|
|
Step 1: Installing plugin files...
|
|
✓ Synced 47 files from GitHub
|
|
|
|
Step 2: Detecting project type...
|
|
✓ GREENFIELD detected (minimal/empty project)
|
|
|
|
Let's create your PROJECT.md:
|
|
|
|
What is your project's primary goal?
|
|
[1] Production application (full-featured app)
|
|
[2] Library/SDK (reusable code for developers)
|
|
[3] Internal tool (company/team utility)
|
|
[4] Learning project (experimental)
|
|
> 1
|
|
|
|
What architecture pattern?
|
|
[1] Monolith (single codebase)
|
|
[2] Microservices (distributed)
|
|
[3] API + Frontend (layered)
|
|
[4] CLI tool
|
|
> 3
|
|
|
|
Primary language?
|
|
[1] Python
|
|
[2] TypeScript/JavaScript
|
|
[3] Go
|
|
[4] Other
|
|
> 1
|
|
|
|
Generating PROJECT.md...
|
|
✓ Created PROJECT.md at root (287 lines)
|
|
|
|
Fill in these sections:
|
|
📝 GOALS - What success looks like
|
|
📝 SCOPE - What's in/out of scope
|
|
📝 CONSTRAINTS - Technical limits
|
|
📝 CURRENT SPRINT - First sprint goals
|
|
|
|
Step 3: Hook configuration...
|
|
[Same as brownfield]
|
|
|
|
Step 4: Validation...
|
|
[Same as brownfield]
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
✓ Setup Complete!
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Sync failed: Network error"
|
|
|
|
```bash
|
|
# Check internet connection
|
|
curl -I https://raw.githubusercontent.com
|
|
|
|
# Manual sync
|
|
/sync --github
|
|
```
|
|
|
|
### "PROJECT.md generation incomplete"
|
|
|
|
This is expected for greenfield projects. Fill in TODO sections manually:
|
|
|
|
```bash
|
|
# Open and edit
|
|
vim PROJECT.md
|
|
|
|
# Then validate
|
|
/align --project
|
|
```
|
|
|
|
### "Hooks not running"
|
|
|
|
Full restart required after setup:
|
|
```bash
|
|
# Quit Claude Code completely (Cmd+Q / Ctrl+Q)
|
|
# Wait 5 seconds
|
|
# Restart Claude Code
|
|
```
|
|
|
|
---
|
|
|
|
## Related Commands
|
|
|
|
- `/sync` - Sync/update plugin files
|
|
- `/align --project` - Validate PROJECT.md alignment
|
|
- `/health-check` - Validate plugin integrity
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
/setup
|
|
│
|
|
├── Step 1: sync_dispatcher.py --github
|
|
│ └── Reliable file installation (Python library)
|
|
│
|
|
├── Step 2: setup-wizard agent (GenAI)
|
|
│ ├── Detect brownfield/greenfield
|
|
│ ├── Analyze codebase (if brownfield)
|
|
│ └── Generate PROJECT.md
|
|
│
|
|
├── Step 3: Hook configuration
|
|
│ └── Optional settings.local.json creation
|
|
│
|
|
└── Step 4: health_check.py
|
|
└── Validate installation
|
|
```
|
|
|
|
**Key Design**: Delegates file installation to `sync_dispatcher.py` (reliable), focuses GenAI on PROJECT.md generation (what it's good at).
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-13
|