Enhance App

Enhance App

Enhance an existing project with Claude Code configuration. Shared files (agents, plan templates) are linked from a central location — not duplicated per project.

Instructions

IMPORTANT: Non-interactive where possible. Complete all steps without pausing unless a decision is required.

Step 1: Pre-flight Check & Scan Existing Config

1. If not a git repo, initialize one: git init
2. Survey what the project already has:

echo "=== Existing Configuration ==="
[ -d .claude/agents ] && echo "  Agents:      $(ls .claude/agents/*.md 2>/dev/null | wc -l) files" || echo "  Agents:      (none)"
[ -d .claude/rules ] && echo "  Rules:       $(ls .claude/rules/*.md 2>/dev/null | wc -l) files" || echo "  Rules:       (none)"
[ -f .claude/settings.json ] && echo "  Settings:    exists" || echo "  Settings:    (none)"
[ -d plans ] && echo "  Plans:       exists" || echo "  Plans:       (none)"
[ -f CLAUDE.md ] && echo "  CLAUDE.md:   exists ($(wc -l < CLAUDE.md) lines)" || echo "  CLAUDE.md:   (none)"
[ -f .mcp.json ] && echo "  MCP:         exists" || echo "  MCP:         (none)"
[ -f marketplace.json ] && echo "  Marketplace: exists" || echo "  Marketplace: (none)"

Step 2: Auto-detect Project Details

Auto-detect as much as possible before asking the user anything:

PROJECT_NAME=$(basename "$PWD")
cat package.json 2>/dev/null
cat README.md 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null
cat go.mod 2>/dev/null
cat pyproject.toml 2>/dev/null

From these files, infer:

• PROJECT_NAME — from directory name or package.json name
• STACK — from dependencies (e.g., next -> "Next.js + TypeScript")
• PROJECT_TYPE — from STACK + README context (web app, API, CLI, library)
• DESCRIPTION — from package.json description or first line of README
• CMD_INSTALL / CMD_DEV / CMD_TEST / CMD_BUILD / CMD_LINT — from package.json scripts

Detect the package manager:

[ -f bun.lockb ] && PM="bun" || { [ -f pnpm-lock.yaml ] && PM="pnpm" || { [ -f yarn.lock ] && PM="yarn" || PM="npm"; }; }

Present a single confirmation with everything pre-filled:

Auto-detected project configuration:

  Project name:  [detected]
  Project type:  [detected]
  Tech stack:    [detected]
  Description:   [detected]
  Install:       [detected]  Dev: [detected]  Test: [detected]
  Build:         [detected]  Lint: [detected]

Press Enter to accept, or type corrections (e.g., "type: SaaS dashboard, description: ...")

Only ask for values that genuinely could not be detected. For anything with a reasonable default, use it without asking.

Store as variables:

• PROJECT_NAME, PROJECT_TYPE, STACK, DESCRIPTION, TEAM
• CMD_INSTALL, CMD_DEV, CMD_TEST, CMD_BUILD, CMD_LINT

Step 2.5: Team Selection

Read teams/teams.json from the template directory (found in Step 3, or check the known locations now). Present the available teams:

Available agent teams:

  1. Enterprise Engineering (default)
     7 agents: backend, frontend, security, test, devops, review, perf
     Best for: Complex apps, internal tools

  2. SaaS Product
     8 agents: + ui-ux-designer, conversion-optimizer
     Best for: SaaS products, dashboards, subscription products

  3. Internal Tool
     8 agents: + ui-ux-designer (practical focus)
     Best for: Admin panels, developer tools, back-office apps

  4. Game / Interactive
     6 agents: + ui-ux-designer, mobile-designer
     Best for: Games, interactive experiences, creative tools

  5. Marketing Site
     6 agents: + all 3 designers, frontend only
     Best for: Landing pages, marketing sites, pricing pages

Select a team (1-5, default 1):

Store the selection as TEAM_ID (one of: enterprise, saas-product, internal-tool, game-interactive, marketing-site). Store the team's display name as TEAM_DISPLAY_NAME. Store the team's agent list from teams.json as TEAM_AGENTS.

Step 3: Find Shared Source

Locate the shared enterprise files. Check these locations in order:

For agents and plan templates (shared — linked, not copied):

1. ~/.claude/shared/enterprise/agents/ and ~/.claude/shared/enterprise/plan-templates/
2. ~/.claude/skills/enhance-app/templates/enhance-app/.claude/agents/ and .../plans/templates/
3. The claude-code-utils repo: templates/enhance-app/ relative to the skill location

Store as SHARED_AGENTS_DIR and SHARED_PLANS_DIR.

For team coordinators (team-specific):

1. ~/.claude/shared/enterprise/teams/$TEAM_ID/coordinator.md
2. ~/.claude/skills/enhance-app/templates/enhance-app/teams/$TEAM_ID/coordinator.md
3. The claude-code-utils repo: templates/enhance-app/teams/$TEAM_ID/coordinator.md

Store as TEAM_COORDINATOR_PATH.

For templates that need per-project customization (rules, CLAUDE.md, hooks, etc.):

1. ~/.claude/skills/enhance-app/templates/enhance-app/
2. The claude-code-utils repo: templates/enhance-app/ relative to the skill location

Store as TEMPLATE_DIR.

If nothing found, print an error with instructions to install from the claude-code-utils repository.

Step 4: Link Shared Files (Team Agents + Plan Templates)

These files are identical across projects — link them, don't copy.

Create the project directories:

mkdir -p .claude/agents plans/templates

Link each agent file from the shared source. Use hardlinks on Windows, symlinks on Unix. Skip files that already exist in the project.

IMPORTANT — Windows (Git Bash / MSYS) hardlink quirk: cmd //c mklink /H requires unquoted literal Windows-style paths. Variable interpolation with backslashes breaks in Git Bash. Use cmd //c "mklink /H <literal-target> <literal-source>" where paths have NO surrounding quotes and NO shell variable expansion with backslashes.

For each file, run an individual cmd //c mklink /H command with the full literal Windows path:

# Example for a single agent file:
cmd //c "mklink /H C:\Users\chris\ProjectDir\.claude\agents\coordinator.md C:\Users\chris\.claude\shared\enterprise\agents\coordinator.md"

On Unix, use symlinks:

ln -s "$SHARED_AGENTS_DIR/coordinator.md" ".claude/agents/coordinator.md"

Fallback: If hardlink/symlink fails, copy the file instead.

4a: Link the team-specific coordinator

Link the coordinator from $TEAM_COORDINATOR_PATH (the team-specific coordinator for the selected $TEAM_ID):

target=".claude/agents/coordinator.md"
[ -f "$target" ] || link_or_copy "$TEAM_COORDINATOR_PATH" "$target"

4b: Link only the agents in the selected team

Read the TEAM_AGENTS list from teams.json for the selected $TEAM_ID. Only link agents that appear in this list — do NOT link all agents from the pool:

# Link only the agents listed in the selected team's "agents" array
for agent_name in $TEAM_AGENTS; do
  source="$SHARED_AGENTS_DIR/${agent_name}.md"
  target=".claude/agents/${agent_name}.md"
  [ -f "$source" ] || continue
  [ -f "$target" ] && continue  # skip existing
  # On Windows: use cmd //c mklink /H with literal Windows paths (see note above)
  # On Unix: ln -s "$source" "$target"
  # Fallback: cp "$source" "$target"
done

4c: Link plan template files (same for all teams)

for template_file in "$SHARED_PLANS_DIR"/*.md; do
  [ -f "$template_file" ] || continue
  link_file "$template_file" "plans/templates/$(basename "$template_file")"
done

Report what was linked vs skipped:

  Team: [TEAM_DISPLAY_NAME] ($TEAM_ID)
  Agents:
    → coordinator.md (linked from teams/$TEAM_ID/)
    → backend-architect.md (linked)
    → ui-ux-designer.md (linked)
    ~ frontend-architect.md (already exists, skipped)
    ...
  Plan templates:
    → feature-plan.md (linked)
    → bugfix-plan.md (linked)
    ...

Step 5: Copy + Customize Per-Project Files

These files need per-project customization — copy them (skip existing):

Rules (copy then auto-populate)

mkdir -p .claude/rules
for rule in architecture api-conventions security-policy code-standards testing-standards env; do
  if [ ! -f ".claude/rules/$rule.md" ]; then
    cp "$TEMPLATE_DIR/.claude/rules/$rule.md" .claude/rules/
  fi
done

After copying, auto-populate rules from codebase analysis. Read the project's package.json, CLAUDE.md, README, and source files to fill in:

• architecture.md — project structure, tech stack, data flow, key patterns
• api-conventions.md — REST/GraphQL/tRPC conventions based on existing endpoints
• code-standards.md — language standards, linting config, import conventions
• testing-standards.md — test framework, naming patterns, coverage expectations
• env.md — environment variables from .env.example or process.env references
• security-policy.md — auth approach, OWASP considerations

Write realistic, useful content — not just variable names. These files should be immediately useful.

CLAUDE.md

if [ ! -f CLAUDE.md ]; then
  cp "$TEMPLATE_DIR/CLAUDE.md" CLAUDE.md
fi

Settings (merge, don't overwrite)

if [ ! -f .claude/settings.json ]; then
  cp "$TEMPLATE_DIR/.claude/settings.json" .claude/settings.json
fi

Marketplace

[ ! -f marketplace.json ] && cp "$TEMPLATE_DIR/marketplace.json" marketplace.json

Step 6: Install Hooks

Merge hooks into existing .claude/settings.json. Read the existing file first, then merge — do not overwrite.

For each hook file in $TEMPLATE_DIR/modules/hooks/ (security-scan, auto-format, type-check, audit-log):

1. Read the hook's JSON content
2. Check if a hook with the same matcher already exists in the settings
3. If not, append it to the appropriate array (PreToolUse or PostToolUse)
4. Write the updated settings.json back

Step 7: Install MCP Servers

If .mcp.json doesn't exist, create it. Auto-detect which MCP servers are relevant based on the codebase:

• github — always include
• filesystem — always include
• postgres/sqlite — include if the project uses a database (check dependencies)
• slack — skip unless the project has slack-related code

if [ ! -f .mcp.json ]; then
  cp "$TEMPLATE_DIR/.mcp.json" .mcp.json
fi

Merge relevant server configs from $TEMPLATE_DIR/modules/mcp/ into the mcpServers object.

Step 8: Append CLAUDE.md Snippets

For each snippet in $TEMPLATE_DIR/modules/claude-md-snippets/:

1. Check if a similar section already exists in CLAUDE.md (search for the header)
2. If not, append the snippet content at the end of CLAUDE.md

Step 9: Replace Placeholders

Replace all collected values in copied files:

PROJECT_SLUG=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-\|-$//g')

TARGET_FILES=$(find . \( -name "CLAUDE.md" -o -path "./.claude/rules/*" -o -name "marketplace.json" -o -name ".mcp.json" \) -type f)

for file in $TARGET_FILES; do
  sed -i "s/\[PROJECT_NAME\]/$PROJECT_NAME/g" "$file"
  sed -i "s/\[YOUR_PROJECT\]/$PROJECT_SLUG/g" "$file"
  sed -i "s|\[e\.g\., SaaS web application / REST API / internal tool\]|$PROJECT_TYPE|g" "$file"
  sed -i "s|\[e\.g\., Next\.js 14 + TypeScript + PostgreSQL + Tailwind\]|$STACK|g" "$file"
  sed -i "s|\[1-2 sentences describing what this project does and who it's for\.\]|$DESCRIPTION|g" "$file"
  sed -i "s|\[Team name or size\]|$TEAM|g" "$file"
  sed -i "s|\[install command\]|$CMD_INSTALL|g" "$file"
  sed -i "s|\[dev command\]|$CMD_DEV|g" "$file"
  sed -i "s|\[test command\]|$CMD_TEST|g" "$file"
  sed -i "s|\[build command\]|$CMD_BUILD|g" "$file"
  sed -i "s|\[lint command\]|$CMD_LINT|g" "$file"
  sed -i "s/\[project-slug\]/$PROJECT_SLUG/g" "$file"
done

Replace team placeholders — generate team-specific content from teams.json:

For [TEAM_NAME]: Replace with $TEAM_DISPLAY_NAME (e.g., "SaaS Product").

For [TEAM_TABLE]: Generate a markdown table from the team's agent list:

| Agent | When to Use |
|---|---|
| `coordinator` | Complex multi-layer tasks, parallel work coordination |
| `ui-ux-designer` | Visual design, design system, brand identity |
...

Each agent's "When to Use" description comes from the agent's description field in its frontmatter.

For [TEAM_WORKFLOWS]: Generate team-specific workflow recommendations based on the team's coordinator. Read the coordinator's Workflow section and produce a condensed version:

**New feature:**
\`\`\`
coordinator → ui-ux-designer (design) → backend + frontend (parallel) → test-engineer → code-reviewer
\`\`\`

Replace in CLAUDE.md and any snippet files that were appended.

Remove the placeholder notice from CLAUDE.md:

sed -i '/Replace all.*PLACEHOLDER.*values/d' CLAUDE.md

Step 10: Generate Project Plans

Analyze the existing codebase to understand what's built, then create stages for what comes next.

Skip this step if plans/active/ already contains stage files.

10a: Analyze the codebase

find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | head -50
cat package.json 2>/dev/null
find . -type f \( -name "*.test.*" -o -name "*.spec.*" \) | head -20
git log --oneline -20 2>/dev/null

Use Grep and Glob tools to understand the tech stack, existing features, patterns, and conventions.

10b: Generate stage breakdown

Based on codebase analysis, determine what stages the project needs. For new projects, generate a full plan. For existing projects, generate stages for what comes next.

Ask the user ONE question:

Based on your codebase, I can generate plans for:
  (a) [inferred direction based on code analysis]
  (b) [alternative direction]
  (c) Something else — describe briefly

Which direction? (a/b/c)

10c: Write stage plan files

Write each stage plan file directly to plans/active/. Each must include:

1. YAML frontmatter (title, type: stage, status: pending, created date, dependencies)
2. Agent directive: > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
3. Goal, Architecture, Tech Stack, Dependencies
4. Task breakdown

For task breakdowns:

• First 3 stages: FULL detail — specific files, failing tests, implementation steps, commit messages, verification
• Remaining stages: Goal, Architecture, Dependencies, and task titles with brief descriptions

Conventions:

• Sequential dependencies — each stage builds on prior stages
• Test-driven — every task starts with failing tests
• Atomic commits — each task ends with a specific commit
• Deliverable verification — each stage ends with verification commands
• Realistic file paths — use actual paths from the codebase

Step 11: Display Summary

================================================================
[TEAM_DISPLAY_NAME] Claude Code configuration installed!
================================================================

Team: [TEAM_DISPLAY_NAME] ($TEAM_ID)

Linked (shared — update once, all projects get it):
  .claude/agents/      — [N] specialist agents (team: $TEAM_ID)
  plans/templates/     — Feature, bugfix, stage, and context-handoff templates

Copied (project-specific):
  .claude/rules/       — Project knowledge base (auto-populated)
  .claude/settings.json — Hooks + permission rules
  plans/active/        — Stage plans (if generated)
  CLAUDE.md            — Project instructions
  .mcp.json            — MCP server configuration
  marketplace.json     — Plugin marketplace catalog

Skipped (already existed):
  [list of what was skipped]

================================================================
AGENT TEAM: [TEAM_DISPLAY_NAME]
================================================================

  coordinator          — orchestrates the team (Opus)
  [for each agent in TEAM_AGENTS, list name and brief description]

================================================================
NEXT STEPS:
================================================================

1. Review .claude/rules/ — auto-populated from your project details.
   Refine if needed: architecture.md, env.md, security-policy.md

2. Execute your first stage plan (if generated):
   - Open plans/active/stage-01-*.md
   - Paste into a new Claude Code session
   - Claude follows it task-by-task (TDD, commits, verification)

3. Restart Claude Code to activate agents, rules, and hooks

4. Try /team-battle to compare different team compositions

================================================================

Step 12: Git Commit

git add .claude/ plans/ marketplace.json .mcp.json CLAUDE.md
git commit -m "chore: add $TEAM_DISPLAY_NAME Claude Code configuration

- [N] specialist agents: $TEAM_ID team (linked from shared source)
- .claude/rules/ knowledge base (auto-populated)
- Hooks: secret scan, auto-format, TypeScript check
- plans/ structure with templates (linked from shared source)
- marketplace.json, .mcp.json, CLAUDE.md"

Error Handling

If shared files cannot be found:

ERROR: Enterprise shared files not found.

Install them first by running install-resources.sh from the claude-code-utils repo:

  cd claude-code-utils
  ./scripts/install-resources.sh enterprise

Or clone the repo:
  git clone https://github.com/[owner]/claude-code-utils
  cd claude-code-utils && ./scripts/install-resources.sh

If linking fails (falls back to copy):

NOTE: Could not create hardlinks (different drive or unsupported filesystem).
      Falling back to file copy. Files won't auto-update from shared source.
      To enable linking, ensure project and ~/.claude/ are on the same drive.