aiwg/agentic/code/frameworks/sdlc-complete/commands/aiwg-setup-warp.md

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

---
description: Setup Warp Terminal with AIWG framework context (preserves existing content)
category: sdlc-setup
argument-hint: [project-directory --interactive --guidance "text"]
allowed-tools: Read, Write, Edit, Glob, Bash
model: sonnet
---

# AIWG Setup Warp

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

## Your Task

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

1. **Detect** AIWG installation path
2. **Read** existing project WARP.md (if present)
3. **Preserve** all user-specific notes, rules, and configuration
4. **Add or update** AIWG framework section with orchestration guidance
5. **Aggregate** all SDLC agents and commands into single WARP.md file
6. **Validate** setup is complete

## Important Context

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

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

**Warp vs Claude**:
- Claude: Separate `.claude/agents/*.md` files
- Warp: Single `WARP.md` file with aggregated content
- Warp loads WARP.md automatically when terminal opens in project directory

## 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 WARP.md

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

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

**Three scenarios**:

1. **No WARP.md** → Create from template
2. **WARP.md exists, no AIWG section** → Intelligently merge
3. **WARP.md exists with AIWG section** → Update AIWG section in place

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

**Key Difference from Claude**: Warp uses single `WARP.md` file, not `.warp/agents/*.md` subdirectories.

### Step 3: Load AIWG Template

Instead of directly reading a template file, you must **call the setup-warp.mjs script** to generate the aggregated WARP.md content:

```bash
# Call setup script to generate WARP.md content
node "$AIWG_PATH/tools/warp/setup-warp.mjs" \
  --target "$PROJECT_DIR" \
  --mode sdlc \
  --dry-run
```

**Script responsibilities**:
1. Read base AIWG orchestration context
2. Aggregate all 58 agent files → "SDLC Agents" section
3. Aggregate all 42+ command files → "SDLC Commands" section
4. Combine into single WARP.md template with proper formatting

**Template structure** (generated by script):

```markdown
# Project Context

<!-- User content preserved above this line -->

---

## AIWG SDLC Framework

{AIWG orchestration overview}

---

## SDLC Agents (58 Specialized Roles)

### Intake Coordinator

**Tools**: Bash, Read, Write, MultiEdit, WebFetch

**Purpose**: Transform intake forms into validated inception plans...

{agent content aggregated from all .md files}

---

## SDLC Commands (42+ Workflows)

### /intake-wizard

**Purpose**: Generate or complete intake forms interactively

{command content aggregated from all .md files}

---
```

### Step 4: Intelligent Merge Strategy

**Same pattern as aiwg-setup-project**:

```python
# Pseudo-code
# Parse existing WARP.md sections
sections = parse_markdown_sections(existing_warp_md)

# Identify user sections (NOT AIWG-managed)
user_sections = [s for s in sections if not is_aiwg_section(s.heading)]

# Identify AIWG sections (to be replaced)
aiwg_sections = [s for s in sections if is_aiwg_section(s.heading)]

# Merge: user first, then AIWG
merged_content = format_sections(user_sections) + "\n\n---\n\n" + aiwg_template
```

**AIWG-managed section headings**:
- `## AIWG SDLC Framework`
- `## SDLC Agents`
- `## SDLC Commands`
- `## Platform Compatibility`
- `## Core Orchestrator`
- `## Natural Language`
- `## Phase Overview`

**User-managed sections** (preserved):
- `# Project Context` (header)
- `## Tech Stack`
- `## Team Conventions`
- `## Project Rules`
- Any custom `##` headings not matching AIWG patterns

### Step 5: Execute Merge

**CRITICAL**: Call the `setup-warp.mjs` script via Bash tool. This script handles all merge logic.

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

```bash
node "$AIWG_PATH/tools/warp/setup-warp.mjs" \
  --target "$PROJECT_DIR" \
  --mode sdlc
```

Script will:
- Generate WARP.md from template
- Aggregate all agents and commands
- Substitute `{AIWG_ROOT}` with actual path
- Create WARP.md in project directory

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

```bash
node "$AIWG_PATH/tools/warp/setup-warp.mjs" \
  --target "$PROJECT_DIR" \
  --mode sdlc
```

Script will:
- Read existing WARP.md
- Preserve all user content
- Append AIWG sections with separator
- Add timestamp marker: `<!-- AIWG SDLC Framework (auto-updated) -->`

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

```bash
node "$AIWG_PATH/tools/warp/setup-warp.mjs" \
  --target "$PROJECT_DIR" \
  --mode sdlc
```

Script will:
- Read existing WARP.md
- Identify and preserve user sections
- Replace AIWG sections with updated content
- Maintain all custom user sections

**Alternative: Dry-run first**

```bash
# Preview changes without writing
node "$AIWG_PATH/tools/warp/setup-warp.mjs" \
  --target "$PROJECT_DIR" \
  --mode sdlc \
  --dry-run
```

### Step 6: Validate Setup

Run validation checks:

```bash
echo ""
echo "======================================================================="
echo "Warp 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: WARP.md updated
if [ -f "$WARP_MD" ]; then
  if grep -q "## AIWG" "$WARP_MD"; then
    echo "✓ WARP.md has AIWG section"
  else
    echo "❌ WARP.md missing AIWG section"
  fi
else
  echo "❌ WARP.md not found"
fi

# Check 3: Agent count
agent_count=$(grep -c "^### " "$WARP_MD" || true)
if [ "$agent_count" -ge 58 ]; then
  echo "✓ WARP.md contains $agent_count agents (expected: 58+)"
else
  echo "⚠️  Warning: WARP.md contains only $agent_count agents (expected: 58+)"
fi

# Check 4: Command count
command_count=$(grep -c "^### /" "$WARP_MD" || true)
if [ "$command_count" -ge 40 ]; then
  echo "✓ WARP.md contains $command_count+ commands (expected: 42+)"
else
  echo "⚠️  Warning: WARP.md contains only $command_count commands (expected: 42+)"
fi

# Check 5: Warp compatibility note
if grep -q "Warp Terminal" "$WARP_MD"; then
  echo "✓ Warp Terminal compatibility documented"
else
  echo "⚠️  Warning: Warp Terminal compatibility not documented"
fi

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

Use Bash tool for validation.

### Step 7: Provide Next Steps

After successful setup, provide clear guidance:

```markdown
# Warp Setup Complete ✓

**Project**: {project-directory}
**AIWG Installation**: {AIWG_PATH}
**WARP.md**: {CREATED | UPDATED | MERGED}

## Changes Made

### WARP.md
- ✓ Added/Updated AIWG framework documentation
- ✓ Aggregated 58 SDLC agents into single file
- ✓ Aggregated 42+ SDLC commands into single file
- ✓ Included Core Platform Orchestrator guidance
- ✓ Added natural language command translations
- {if existing WARP.md} ✓ Preserved all user content

### User Content Preserved
- ✓ Project-specific rules
- ✓ Tech stack preferences
- ✓ Team conventions
- ✓ {N} custom sections preserved

## Next Steps

1. **Initialize Warp**:
   ```bash
   # Open project in Warp Terminal
   cd {project-directory}

   # Warp will automatically load WARP.md
   # Or manually trigger: warp /init
   ```

2. **Test Natural Language**:
   - "Let's transition to Elaboration"
   - "Run security review"
   - "Where are we?"

3. **Use Slash Commands**:
   - Type `/` in Warp input field
   - Browse available commands
   - Execute SDLC workflows

4. **Check WARP.md**:
   - Review aggregated agents and commands
   - Verify user content preserved
   - Add project-specific notes if needed

## Warp Terminal Usage

**Warp automatically loads WARP.md** when you:
- Open terminal in project directory
- Run `warp /init` manually
- Edit files in the project

**Natural language examples**:
- "transition to Elaboration" → Orchestrates phase transition
- "run security review" → Executes security validation
- "create architecture baseline" → Generates SAD + ADRs

## Resources

- **AIWG Framework**: {AIWG_PATH}/agentic/code/frameworks/sdlc-complete/README.md
- **Warp Documentation**: https://docs.warp.dev/knowledge-and-collaboration/rules
- **Natural Language Guide**: {AIWG_PATH}/docs/simple-language-translations.md
- **Orchestrator Docs**: {AIWG_PATH}/docs/orchestrator-architecture.md
- **Multi-Agent Pattern**: {AIWG_PATH}/docs/multi-agent-documentation-pattern.md

## Troubleshooting

**Setup Script Not Found**:
```bash
# Verify AIWG installation
ls {AIWG_PATH}/tools/warp/setup-warp.mjs

# If missing, reinstall AIWG
aiwg -reinstall
```

**WARP.md Not Loading in Warp**:
- Ensure WARP.md is in project root (not subdirectory)
- Check file permissions: `chmod 644 WARP.md`
- Restart Warp Terminal
- Manually trigger: `warp /init`

**Agent/Command Count Too Low**:
- Verify AIWG installation is complete
- Re-run setup: `/aiwg-setup-warp`
- Check for errors in setup-warp.mjs output

**Need to Update WARP.md Again**:
```bash
# Safe to run multiple times - preserves user content
/aiwg-setup-warp

# Or use update command explicitly
/aiwg-update-warp
```
```

## Implementation Notes

**Tools to Use**:
1. **Bash**: Resolve AIWG path, call setup-warp.mjs script, run validation
2. **Read**: Check existing WARP.md before merge
3. **Grep**: Detect AIWG section presence, count agents/commands
4. **Script Execution**: Call `setup-warp.mjs` for all merge operations

**Critical Success Factors**:
- ✅ Preserve ALL user content (never delete existing notes)
- ✅ Call `setup-warp.mjs` script (don't manually merge)
- ✅ Substitute `{AIWG_ROOT}` with actual resolved path
- ✅ Include complete AIWG section (orchestration, agents, commands)
- ✅ Validate setup before declaring success

**Error Handling**:
- If AIWG not found → Fail with install instructions
- If setup-warp.mjs not found → Fail with reinstall instructions
- If WARP.md unparseable → Script handles with warning
- If permissions denied → Fail with permission error

## Success Criteria

This command succeeds when:
- [ ] AIWG installation path resolved and validated
- [ ] setup-warp.mjs script executed successfully
- [ ] WARP.md created or updated with complete AIWG section
- [ ] All existing user content preserved (if existing WARP.md)
- [ ] `{AIWG_ROOT}` placeholder replaced with actual path
- [ ] Agent count ≥ 58
- [ ] Command count ≥ 42
- [ ] Validation checks pass
- [ ] Clear next steps provided to user
- [ ] Natural language translation guide documented

## Script Parameters

When calling `setup-warp.mjs`:

**Required**:
- `--target <path>`: Target project directory

**Optional**:
- `--mode <type>`: Mode: general, sdlc, or both (default: sdlc)
- `--dry-run`: Preview changes without writing
- `--force`: Overwrite WARP.md (discard user content) - USE WITH CAUTION

**Examples**:

```bash
# Standard setup (preserves user content)
node "$AIWG_PATH/tools/warp/setup-warp.mjs" --target "$PROJECT_DIR" --mode sdlc

# Preview without writing
node "$AIWG_PATH/tools/warp/setup-warp.mjs" --target "$PROJECT_DIR" --dry-run

# Force overwrite (DANGEROUS - discards user content)
node "$AIWG_PATH/tools/warp/setup-warp.mjs" --target "$PROJECT_DIR" --force
```

---

**Command Version**: 1.0
**Category**: SDLC Setup
**Mode**: Interactive Setup and Configuration
**Platform**: Warp Terminal