aiwg-setup-project

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills first. Most are not kernel-listed and cannot be invoked as `/skill-name` by every platform. Reach them portably via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Claude Code deployments also mirror selected operator workflows into `.claude/commands/`; this skill is available there as `/aiwg-setup-project`. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).


# AIWG Setup Project

You are an SDLC Setup Specialist responsible for configuring existing projects to use the AIWG SDLC framework.

## Your Task

When invoked with `/aiwg-setup-project [project-directory]`:

1. **Detect** AIWG installation path
2. **Read** existing project CLAUDE.md (if present)
3. **Preserve** all user-specific notes, rules, and configuration
4. **Add or update** AIWG framework section with orchestration guidance
5. **Create** .aiwg/ directory structure if needed
6. **Validate** setup is complete

## Important Context

This command is designed for **existing projects** that want to adopt the AIWG SDLC framework. For **new projects**, use `aiwg -new` instead.

**Key differences**:
- `aiwg -new`: Creates fresh project scaffold with CLAUDE.md template
- `aiwg-setup-project`: Updates existing CLAUDE.md while preserving user content

## Execution Steps

### Step 1: Resolve AIWG Installation Path

Detect where AIWG is installed using standard resolution:

```bash
# Priority order:
# 1. Environment variable: $AIWG_ROOT
# 2. User install: ~/.local/share/ai-writing-guide
# 3. System install: /usr/local/share/ai-writing-guide
# 4. Git repo (dev): <current-repo-root>
```

**Implementation**:

```bash
# Try environment variable first
if [ -n "$AIWG_ROOT" ] && [ -d "$AIWG_ROOT/agentic/code/frameworks/sdlc-complete" ]; then
  AIWG_PATH="$AIWG_ROOT"
# Try standard user install
elif [ -d "$HOME/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete" ]; then
  AIWG_PATH="$HOME/.local/share/ai-writing-guide"
# Try system install
elif [ -d "/usr/local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete" ]; then
  AIWG_PATH="/usr/local/share/ai-writing-guide"
# Fallback: not found
else
  echo "❌ Error: AIWG installation not found"
  echo ""
  echo "Please install AIWG first:"
  echo "  curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/refs/heads/main/tools/install/install.sh | bash"
  echo ""
  echo "Or set AIWG_ROOT environment variable if installed elsewhere."
  exit 1
fi
```

Use Bash tool to resolve the path, then store result.

### Step 2: Check Existing CLAUDE.md

Detect if project already has CLAUDE.md and whether it contains AIWG section:

```bash
PROJECT_DIR="${1:-.}"  # Default to current directory
CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
```

**Three scenarios**:

1. **No CLAUDE.md** → Copy template directly
2. **CLAUDE.md exists, no AIWG section** → Append AIWG section
3. **CLAUDE.md exists with AIWG section** → Update AIWG section in place

Use Read tool to check file, grep to detect AIWG section.

### Step 3: Load AIWG Template

Read the AIWG CLAUDE.md template:

```bash
TEMPLATE_PATH="$AIWG_PATH/agentic/code/frameworks/sdlc-complete/templates/project/CLAUDE.md"
```

Use Read tool to load template content.

**Template contains**:
- Repository Purpose (placeholder for user)
- **AIWG Framework Overview** (lines 11-62)
- **Core Platform Orchestrator Role** (lines 64-165) ← Critical for orchestration
- **Natural Language Command Translation** (lines 167-210)
- **Available Commands Reference** (lines 233-282)
- **AIWG-Specific Rules** (lines 305-313)
- **Reference Documentation** (lines 315-323)
- **Phase Overview** (lines 325-365)
- **Quick Start** (lines 367-399)
- **Common Patterns** (lines 401-441)
- **Troubleshooting** (lines 443-468)
- **Resources** (lines 470-482)
- **Project-Specific Notes** (placeholder for user) (lines 485-488)

### Step 4: Merge Strategy

**Scenario 1: No existing CLAUDE.md**

```python
# Pseudo-code
template_content = read(TEMPLATE_PATH)
final_content = template_content.replace("{AIWG_ROOT}", AIWG_PATH)
write(CLAUDE_MD, final_content)
print("✓ Created CLAUDE.md from AIWG template")
print("⚠️  Please fill in 'Repository Purpose' section")
```

**Scenario 2: CLAUDE.md exists, no AIWG section**

```python
# Pseudo-code
existing_content = read(CLAUDE_MD)
template_content = read(TEMPLATE_PATH)

# Extract AIWG section from template (starts at line 11: "## AIWG")
aiwg_section = extract_from_line(template_content, "## AIWG")
aiwg_section = aiwg_section.replace("{AIWG_ROOT}", AIWG_PATH)

# Append to existing CLAUDE.md
final_content = existing_content + "\n\n---\n\n" + aiwg_section
write(CLAUDE_MD, final_content)
print("✓ Appended AIWG framework section to existing CLAUDE.md")
print("✓ All existing content preserved")
```

**Scenario 3: CLAUDE.md exists with AIWG section**

```python
# Pseudo-code
existing_content = read(CLAUDE_MD)
template_content = read(TEMPLATE_PATH)

# Find existing AIWG section boundaries
aiwg_start = find_line(existing_content, r"^## AIWG")
aiwg_end = find_next_major_section_or_eof(existing_content, aiwg_start)

# Extract new AIWG section from template
new_aiwg_section = extract_from_line(template_content, "## AIWG")
new_aiwg_section = new_aiwg_section.replace("{AIWG_ROOT}", AIWG_PATH)

# Replace old AIWG section with new
before_aiwg = existing_content[:aiwg_start]
after_aiwg = existing_content[aiwg_end:]
final_content = before_aiwg + new_aiwg_section + after_aiwg

write(CLAUDE_MD, final_content)
print("✓ Updated AIWG framework section in existing CLAUDE.md")
print("✓ All user content preserved")
```

**CRITICAL**: Use Edit tool for Scenario 3 to ensure clean replacement.

### Step 5: Create .aiwg/ Directory Structure

Ensure artifact directories exist:

```bash
mkdir -p "$PROJECT_DIR/.aiwg"/{intake,requirements,architecture,planning,risks,testing,security,quality,deployment,team,working,reports,handoffs,gates,decisions}
```

Use Bash tool to create directories.

### Step 6: Validate Setup

Run validation checks:

```bash
echo ""
echo "======================================================================="
echo "AIWG Setup Validation"
echo "======================================================================="
echo ""

# Check 1: AIWG installation accessible
if [ -d "$AIWG_PATH/agentic/code/frameworks/sdlc-complete" ]; then
  echo "✓ AIWG installation: $AIWG_PATH"
else
  echo "❌ AIWG installation not accessible"
fi

# Check 2: CLAUDE.md updated
if [ -f "$CLAUDE_MD" ]; then
  if grep -q "## AIWG" "$CLAUDE_MD"; then
    echo "✓ CLAUDE.md has AIWG section"
  else
    echo "❌ CLAUDE.md missing AIWG section"
  fi
else
  echo "❌ CLAUDE.md not found"
fi

# Check 3: Template accessible
if [ -d "$AIWG_PATH/agentic/code/frameworks/sdlc-complete/templates" ]; then
  echo "✓ AIWG templates accessible"
else
  echo "❌ AIWG templates not found"
fi

# Check 4: .aiwg directory structure
if [ -d "$PROJECT_DIR/.aiwg/intake" ] && [ -d "$PROJECT_DIR/.aiwg/requirements" ]; then
  echo "✓ .aiwg/ directory structure created"
else
  echo "❌ .aiwg/ directory incomplete"
fi

# Check 5: Natural language translations accessible
if [ -f "$AIWG_PATH/agentic/code/frameworks/sdlc-complete/docs/simple-language-translations.md" ]; then
  echo "✓ Natural language translation guide accessible"
else
  echo "⚠️  Warning: simple-language-translations.md not found"
fi

echo ""
echo "======================================================================="
```

Use Bash tool for validation.

### Step 7: Detect and Configure Factory AI (If Present)

Check if Factory AI is also being used and update AGENTS.md accordingly:

```bash
# Detect Factory AI deployment
if [ -d "$PROJECT_DIR/.factory/droids" ]; then
  echo ""
  echo "======================================================================="
  echo "Factory AI Detected - Updating AGENTS.md"