jmagly/aiwg-setup-warp

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:

# 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:

# 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:

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:

# 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):

# 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:

# 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

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

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

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

# 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:

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:

# 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:

# 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:

# 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

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/agent-deployment.md — Rules for working with agent definitions and multi-provider deployment
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/human-authorization.md — Seek explicit authorization before overwriting user content in WARP.md
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Detect AIWG installation and WARP.md state before making changes
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/aiwg-update-warp/SKILL.md — Companion skill for updating an already-configured Warp project
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/aiwg-setup-project/SKILL.md — Analogous Claude Code setup skill; shares same merge strategy pattern