Enhance Existing Project

Instructions

IMPORTANT: Execute immediately. Do NOT explore the codebase first or propose a plan. Start Step 1 right now.

Default mode is Full Enhancement (resources + analysis + improvements). If the user passed an argument, select the matching mode:

• resources → Steps 1-7 only (add agents, skills, CLAUDE.md - no code changes)
• analysis → Steps 1-4, 8 only (report only, no changes)
• improvements → Steps 1-4, 9-10 only (fix issues, refactor, add tests)
• claudemd → Steps 1-4, 7 only (review/improve CLAUDE.md only)
• No argument or full → Full Enhancement (all steps)

Step 1: Validate Target Project

TARGET_DIR="${1:-.}"
TARGET_DIR=$(cd "$TARGET_DIR" && pwd)

if [ ! -d "$TARGET_DIR" ]; then
  echo "❌ Directory does not exist: $TARGET_DIR"
  exit 1
fi

if [ ! -f "$TARGET_DIR/package.json" ] && \
   [ ! -f "$TARGET_DIR/Cargo.toml" ] && \
   [ ! -f "$TARGET_DIR/pyproject.toml" ] && \
   [ ! -f "$TARGET_DIR/go.mod" ] && \
   [ ! -f "$TARGET_DIR/pom.xml" ] && \
   [ ! -f "$TARGET_DIR/build.gradle" ]; then
  echo "⚠️  No recognized project manifest found"
fi

cd "$TARGET_DIR" || exit 1
PROJECT_NAME=$(basename "$TARGET_DIR")

echo ""
echo "🔧 Enhancing project: $PROJECT_NAME"
echo "📁 Location: $TARGET_DIR"
echo ""

Step 2: Detect Project Type and Tech Stack

Use Glob to find manifest files and Read the main ones (package.json, etc.) to detect:

• Primary language (TypeScript, JavaScript, Python, Go, Rust, Java)
• Framework (Next.js, Express, React, FastAPI, etc.)
• Build tools (npm, yarn, pnpm, cargo, pip, go)
• Testing framework (Jest, Vitest, Pytest, etc.)
• Database (if present)

Do this with direct Glob + Read calls, NOT an Explore agent. Keep it under 30 seconds.

Step 3: Check Existing Claude Code Resources

echo "🔍 Checking existing Claude Code resources..."

if [ -d ".claude/agents" ]; then
  AGENT_COUNT=$(find .claude/agents -name "*.md" 2>/dev/null | wc -l)
  echo "   ✓ Agents directory exists ($AGENT_COUNT agents)"
else
  echo "   ○ No agents directory"
fi

if [ -d ".claude/skills" ]; then
  SKILL_COUNT=$(find .claude/skills -maxdepth 2 -name "SKILL.md" 2>/dev/null | wc -l)
  echo "   ✓ Skills directory exists ($SKILL_COUNT skills)"
else
  echo "   ○ No skills directory"
fi

if [ -f "CLAUDE.md" ]; then
  echo "   ✓ CLAUDE.md exists"
else
  echo "   ○ No CLAUDE.md"
fi

if [ -d "plans" ]; then
  echo "   ✓ Plans directory exists"
else
  echo "   ○ No plans directory"
fi

Step 4: Assess Existing CLAUDE.md Quality

If CLAUDE.md exists, Read it and score against these criteria (0-100):

• Completeness (25 pts): Has Overview, Tech Stack, Project Structure, Commands, Key Files sections
• Accuracy (25 pts): Tech stack matches manifests, file paths exist, commands work
• Specificity (20 pts): Contains project-specific patterns, not generic boilerplate
• Code Examples (15 pts): Has actual code examples from this project
• Maintenance (15 pts): Versions match current dependencies, no stale info

If score < 80, note improvements needed. Present the score to the user.

Step 5: Copy Agents

mkdir -p .claude/agents

# Based on detected tech stack, select appropriate agents:
# - All projects: codebase-explorer, pattern-finder, debugger
# - Web projects: add ui-ux-designer, component-builder, api-developer
# - API projects: add api-developer, test-writer, architecture-planner
# - Libraries: add test-writer, pattern-finder, dependency-analyzer

Copy agents from the global ~/.claude/agents/ directory into the project's .claude/agents/. Create subdirectories (explore/, plan/, implement/, design/) as needed.

Step 6: Copy Skills

mkdir -p .claude/skills

# Core workflow skills (all projects)
CORE_SKILLS="ship verify-work organize-commits track-progress"

# Development skills
DEV_SKILLS="create-plan plan-status generate-tests performance-check"

# Git workflow skills
GIT_SKILLS="worktree-create worktree-sync worktree-cleanup"

Copy skills from the global ~/.claude/skills/ directory into the project's .claude/skills/.

Step 7: Create/Update CLAUDE.md

If no CLAUDE.md exists, or if the quality score from Step 4 is < 80:

1. Select the appropriate template from templates/claude-md/ based on detected tech stack:

   • Next.js → nextjs-app.md
   • Express/Fastify/NestJS → api-service.md
   • CLI tool → cli-tool.md
   • React library → node-library.md
   • Python project → python-app.md
   • Game → game-browser.md
   • Unknown → minimal.md

2. If creating new: Generate from template, replacing placeholders with actual values

3. If improving existing: Preserve custom content, fix low-scoring sections only

4. Validate the result meets quality standards

Step 8: Run Codebase Analysis

Invoke three agents in parallel using the Task tool in a single message:

1. codebase-explorer - "Analyze this project and report: primary language/version, frameworks, project structure pattern, key directories, build/test configuration"

2. dependency-analyzer - "Analyze dependencies: security vulnerabilities, outdated packages, unused dependencies, circular dependencies, license compatibility"

3. pattern-finder - "Identify code patterns: style/formatting conventions, naming conventions, import patterns, error handling, testing patterns, documentation patterns"

Wait for all three to complete, then synthesize findings into a report for the user.

Step 9: Generate Tests

1. Identify untested code by comparing source files to test files
2. Invoke /generate-tests using the Skill tool to create missing test files
3. Report what was generated

Step 10: Apply Code Improvements

IMPORTANT: This step makes actual code changes. Confirm with the user before proceeding.

1. Invoke both in parallel using the Skill tool in a single message:

   • /verify-work - security, best practices, standards
   • /performance-check - performance anti-patterns

2. Present findings to the user and get approval to fix

3. Apply fixes for approved issues:

   • Security vulnerabilities (blocking)
   • Performance bottlenecks
   • Code standard violations

Step 11: Create Development Plan

1. Invoke /create-plan using the Skill tool with name "improvements"
2. This creates plans/active/improvements/plan.md with prioritized tasks based on analysis

Step 12: Organize Commits (if changes were made)

1. Invoke /organize-commits using the Skill tool to create logical commits:

   • feat: add Claude Code agents and skills
   • refactor: improve code structure (if improvements applied)
   • fix: resolve security issues (if security fixes applied)
   • test: add comprehensive test coverage (if tests generated)
   • docs: add CLAUDE.md and improve documentation

2. Invoke /track-progress using the Skill tool to record enhancements

Step 13: Generate Enhancement Report

Present a summary:

## Enhancement Complete: [PROJECT_NAME]

### Resources Added
- Agents: [count] agents in .claude/agents/
- Skills: [count] skills in .claude/skills/
- CLAUDE.md: [created/improved] (quality score: [X]/100)

### Analysis Results
- [Summary from codebase-explorer]
- [Summary from dependency-analyzer]
- [Summary from pattern-finder]

### Code Improvements
- Security issues fixed: [count]
- Performance issues fixed: [count]
- Tests generated: [count] files

### Next Steps
1. Review CLAUDE.md for accuracy
2. Check plans/active/improvements/plan.md for suggested tasks
3. Use /plan-status to track improvements
4. Use /ship at the end of each session

Reference

Enhancement vs Starter Project

Tips

• Backup first: Consider committing before enhancing
• Review CLAUDE.md: Generated conventions may need adjustment
• Check the plan: Improvement plan prioritizes based on analysis
• Re-run analysis: Use analysis mode after making changes