AIWG – Agentic AI Workflow Guide

Modular toolkit for AI-powered SDLC, marketing, and content workflows.

npm i -g aiwg        # install globally
aiwg use sdlc        # deploy SDLC framework

Get Started · Documentation · Examples · Contributing · Community

🌐 Live demo & docs: https://jmagly.github.io/ai-writing-guide

---

🚀 Quick Start

Prerequisites: Node.js ≥18.0.0 and an AI platform (Claude Code, GitHub Copilot, Warp Terminal, or others)

Option A: Claude Code Plugin (Recommended for Claude Code users)

# Add AIWG marketplace (one-time setup)
/plugin marketplace add jmagly/ai-writing-guide

# Install the frameworks you need
/plugin install sdlc@aiwg        # SDLC framework (64 agents)
/plugin install marketing@aiwg   # Marketing framework (37 agents)
/plugin install utils@aiwg       # Core utilities
/plugin install voice@aiwg       # Voice profiles

No account required - Claude Code plugins use decentralized git-based distribution. No registry signup, no approval process - just add and install.

Option B: npm Install (CLI + Multi-Platform)

# Install
npm install -g aiwg

# Activate on your project
cd your-project
aiwg use sdlc

# Or scaffold a new project with everything set up
aiwg -new my-project

Alternative: Bleeding edge install

Direct from main branch (latest features, may be experimental):

curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash

This installs directly from the HEAD of the main branch - you get the newest features first, but they may not be as stable as npm releases. Use this if you want to stay on the cutting edge.

Switch between modes (after npm install):

aiwg --use-main      # Track main branch (bleeding edge)
aiwg --use-stable    # Back to npm releases (recommended)

Choose your framework:

cd your-project

# Deploy SDLC framework (software development)
aiwg use sdlc              # 64 agents, 97 commands, aiwg-utils

# Deploy Marketing framework
aiwg use marketing         # 37 agents, 23 commands

# Deploy all frameworks
aiwg use all

Platform-specific options

# Warp Terminal (creates WARP.md)
aiwg use sdlc --provider warp

# Factory AI (creates .factory/droids/ + AGENTS.md)
aiwg use sdlc --provider factory

# OpenCode (creates .opencode/agent/ + AGENTS.md)
aiwg use sdlc --provider opencode

# Cursor (creates .cursor/rules/ + AGENTS.md)
aiwg use sdlc --provider cursor

# GitHub Copilot (creates .github/agents/*.yaml + copilot-instructions.md)
aiwg use sdlc --provider copilot

# OpenAI/Codex (experimental)
aiwg use sdlc --provider openai

Model selection options

# Override model for reasoning-tier agents (opus)
aiwg use sdlc --reasoning-model claude-opus-4-2

# Override model for coding-tier agents (sonnet)
aiwg use sdlc --coding-model claude-sonnet-5

# Override multiple tiers and save for future deployments
aiwg use sdlc --reasoning-model opus-4-2 --coding-model sonnet-5 --save

# Only update specific agents
aiwg use sdlc --filter "*architect*" --reasoning-model opus-4-2

# Only update reasoning-tier agents
aiwg use sdlc --filter-role reasoning --reasoning-model custom-model

See Model Configuration Guide for details.

Start a new project — Full SDLC scaffolding in seconds:

aiwg -new my-awesome-project
cd my-awesome-project
# Ready to go! Intake forms, agents, and commands deployed.

💡 What just happened? You now have 93 specialized AI agents and 76 workflow commands ready to help you write better content, manage projects, run campaigns, and ship faster.

---

✨ What You Get

📦 Modular Architecture: AIWG is a framework toolkit with three component types:

• Frameworks — Complete lifecycle solutions (SDLC Complete, Media/Marketing Kit)
• Addons — Standalone utilities that work with any framework or independently (Writing Quality)
• Extensions — Framework-specific modules (GDPR compliance, FTC guidelines)

🏗️ SDLC Complete Framework Manage projects like an enterprise. Scale like a startup. ✅ 64 SDLC agents — Requirements, architecture, testing, security, deployment ✅ 97 workflow commands — Intake, phase gates, risk management, compliance ✅ 172 templates — Every artifact from concept to production ✅ Multi-agent orchestration — Parallel reviews, synthesis, automated quality gates ✅ Extensions available — GDPR compliance, legal frameworks Perfect for: Solo developers, small teams (2-10), enterprise projects with compliance requirements

📣 Media/Marketing Kit (MMK) Run campaigns like an agency. Ship content faster. ✅ 37 marketing agents — Strategy, content, creative, analytics, compliance ✅ 23 workflow commands — Campaign kickoff, content planning, brand review ✅ 103 templates — 15 categories from intake to analytics ✅ 5-phase lifecycle — Strategy → Creation → Review → Publication → Analysis ✅ Extensions available — FTC compliance, industry-specific guidelines Perfect for: Marketing teams, product launches, agencies needing consistent deliverable quality

🔧 Reliability Patterns

Research-backed patterns for robust AI workflows.

✅ Agent Design Bible — 10 Golden Rules based on academic research ✅ Agent Linter — Validate agents against best practices ✅ @-Mention Traceability — Live doc references in code

✅ Failure Mode Mitigations — Address 4 LLM failure archetypes ✅ Deploy Generators — Docker/K8s config generation ✅ Evals Framework — Automated agent behavior testing

📝 Writing Quality Addon

Control your voice. Write naturally. A standalone addon that works with any framework or independently.

✅ Voice Framework — 4 built-in voice profiles (technical, friendly, executive, casual) ✅ 4 voice skills — Apply, create, blend, analyze voices ✅ 3 specialized agents — Validate, optimize, diversify content

✅ Custom voice profiles — Define and save your brand's unique voice ✅ Framework-agnostic — Use standalone or with SDLC/MMK ✅ Zero dependencies — Works immediately after install

🧪 Testing Quality Addon

Enforce TDD. Validate quality. Research-backed testing enforcement, quality metrics, and automation.

✅ TDD Enforcement — Pre-commit hooks + CI coverage gates (80%+ target) ✅ Mutation Testing — Validate tests beyond coverage (Stryker/PITest/mutmut) ✅ Flaky Test Detection — Identify unreliable tests from CI history

✅ Flaky Test Fixes — Pattern-based auto-repair (timing, async, state) ✅ Test Data Factories — Auto-generate factories from schemas (Faker.js) ✅ Test Sync — Detect orphaned tests, missing tests, code misalignment

Research Foundation: Kent Beck (TDD), Google Testing Blog (80% coverage), FlaKat (flaky detection), UTRefactor (test maintenance)

---

🎬 See It In Action

Voice Framework: Same Content, Different Voices

🔧 Technical Authority Voice

The authentication module implements JWT with RS256 signing,
rotating keys every 24 hours. Session tokens expire after 15
minutes of inactivity. We chose this over OAuth2 implicit flow
because our threat model prioritizes server-side validation.

Characteristics: Precise terminology, implementation details, trade-off reasoning

💬 Friendly Explainer Voice

Think of our login system like a building with security badges.
You get a temporary badge (JWT token) when you sign in, and it
automatically expires if you walk away. We refresh your badge
quietly in the background so you never get locked out mid-task.

Characteristics: Analogies, accessible language, reader-focused benefits

📊 Executive Brief Voice

Authentication: Enterprise-grade JWT implementation with automatic
key rotation. Security posture exceeds SOC2 requirements. Zero
production incidents in 18 months. 99.99% uptime on auth services.

Characteristics: Metrics-driven, compliance-focused, outcome-oriented

SDLC Workflow: Inception → Production

# 1. Generate project intake
/intake-wizard "Build customer portal with real-time chat"

# 2. Validate vision and approve phase transition (automated gate check)
/flow-inception-to-elaboration

# 3. Generate architecture document with multi-agent review
#    (Primary Author → 4 Parallel Reviewers → Synthesizer → Baseline)
"Create Software Architecture Document"

# 4. Execute dual-track iteration (Discovery + Delivery in parallel)
/flow-iteration-dual-track 3

# 5. Deploy to production with automated rollback strategy
/flow-deploy-to-production

---

📦 What's Inside

Architecture Overview

aiwg/
├── 🏗️ Frameworks (Complete lifecycle solutions)
│   │
│   ├── sdlc-complete/                    → Enterprise software development
│   │   ├── agents/ (64)                  → Requirements, architecture, testing, security, DevOps
│   │   ├── commands/ (97)                → Intake, phase gates, deployments, compliance
│   │   ├── templates/ (172)              → Every artifact from concept → production
│   │   ├── flows/                        → Phase workflows (Inception → Transition)
│   │   └── extensions/                   → GDPR compliance, legal frameworks
│   │
│   └── media-marketing-kit/              → Marketing campaign management
│       ├── agents/ (37)                  → Strategy, content, creative, analytics
│       ├── commands/ (23)                → Campaign kickoff, content planning, brand review
│       ├── templates/ (103)              → 15 categories from intake to analytics
│       ├── flows/                        → 5-phase lifecycle (Strategy → Analysis)
│       └── extensions/                   → FTC compliance, industry-specific
│
├── 📝 Addons (Standalone utilities — work with any framework)
│   │
│   ├── writing-quality/                  → Content validation and writing improvement
│   │   ├── agents/ (3)                   → writing-validator, prompt-optimizer, content-diversifier
│   │   ├── core/                         → Philosophy and sophistication principles
│   │   ├── examples/                     → Before/after rewrites
│   │   └── context/                      → Quick-reference for different voices
│   │
│   ├── voice-framework/                  → Voice profiles for consistent, natural writing
│   │   ├── skills/ (4)                   → voice-apply, voice-create, voice-blend, voice-analyze
│   │   └── voices/templates/             → Built-in profiles (technical, friendly, executive, casual)
│   │
│   └── testing-quality/                  → Research-backed testing enforcement
│       ├── skills/ (6)                   → tdd-enforce, mutation-test, flaky-detect, flaky-fix, generate-factory, test-sync
│       └── scripts/                      → TDD setup automation
│
├── 🗂️ Workspace Management
│   ├── Framework isolation               → Run SDLC + MMK + addons simultaneously
│   ├── Natural language routing           → "Transition to Elaboration" → auto-routes to SDLC
│   ├── Plugin system                      → Install/uninstall frameworks, addons, extensions
│   └── Cross-framework reads              → MMK reads SDLC artifacts (novel combinations)
│
└── 🛠️ CLI & Tools
    ├── aiwg use <framework>              → Deploy framework (sdlc, marketing, all)
    ├── aiwg list                         → List installed frameworks
    ├── aiwg remove <id>                  → Remove a framework
    ├── aiwg -new                         → Scaffold new project
    └── aiwg -update                      → Update installation

Agent Catalog Highlights

Requirements & Planning:

• requirements-analyst — Transform vague ideas into detailed specs
• system-analyst — Bridge business intent and technical delivery
• intake-coordinator — Validate intake forms and assign agents

Architecture & Design:

• architecture-designer — Design scalable, maintainable systems
• api-designer — Design and evolve API contracts
• cloud-architect — Multi-cloud infrastructure design (AWS/Azure/GCP)

Quality & Testing:

• test-engineer — Comprehensive test suites (unit, integration, E2E)
• code-reviewer — Focus on quality, security, performance
• performance-engineer — Profile bottlenecks, optimize queries

Security & Compliance:

• security-gatekeeper — Enforce security gates before release
• security-auditor — OWASP compliance, vulnerability scanning
• privacy-officer — GDPR/CCPA/HIPAA compliance
• accessibility-specialist — WCAG 2.1 AA/AAA compliance

Operations & DevOps:

• devops-engineer — CI/CD pipelines, infrastructure as code
• incident-responder — Production incident triage and resolution
• reliability-engineer — SLO/SLI definition, capacity planning
• deployment-manager — Release planning and operational readiness

Agent Catalogs:

• SDLC Agents (53) — Software development lifecycle
• Marketing Agents (37) — Campaign and content management
• Writing Agents (3) — Content validation and optimization

---

🎯 Who Is This For?

👤 Solo Developers You wear all the hats. We provide the structure. Start projects quickly with templates Generate intake/architecture docs automatically Validate quality with multi-agent reviews Ship faster without sacrificing rigor Best for: Individual contributors managing full stack

👥 Small Teams (2-10) Scale from chaos to process without heavyweight tools. Standardize artifacts across team Automated phase gates prevent rework Clear handoffs between roles Audit trail for compliance Scales From: 1 solo dev → 10+ team members

🏢 Enterprise Teams Comprehensive lifecycle management. Zero vendor lock-in. Full Inception → Production coverage Compliance-ready (GDPR, SOC2, HIPAA add-ons) Multi-agent orchestration patterns Self-hosted, zero data collection Support: Fortune 500 → boutique agencies

---

🧩 Use Cases

Use Case 1: Apply Consistent Voice Across Content

Problem: Your documentation sounds inconsistent—technical docs read casually, marketing copy sounds robotic.

Solution: Use voice profiles to ensure every piece of content matches your intended tone and audience.

# Deploy writing quality addon (included with any framework)
aiwg use sdlc   # or: aiwg use all

# Apply a voice profile to your content
"Apply technical-authority voice to docs/architecture.md"

# Create a custom voice for your brand
"Create a voice profile based on our existing blog posts"

---

Use Case 2: Deploy Full SDLC Framework

Problem: Setting up consistent templates and agents across projects is tedious.

Solution: One command deploys 53 agents + 48 commands + 156 templates + aiwg-utils.

Claude Code:

aiwg use sdlc

Warp Terminal:

aiwg use sdlc --provider warp

Factory AI:

aiwg use sdlc --provider factory

---

Use Case 3: Generate Intake From Existing Codebase

Problem: Brownfield project. No docs. Need to baseline for new team members.

Solution: Analyze codebase, generate comprehensive intake automatically.

Claude Code:

/intake-from-codebase .

Warp Terminal:

# In Warp AI
"Analyze this codebase and generate intake documents"

Factory AI:

/intake-from-codebase .

Output: Project intake, solution profile, option matrix

---

Use Case 4: Multi-Agent Architecture Review

Problem: Architecture docs need multiple perspectives (security, testing, operations).

Solution: Orchestrate parallel reviews, synthesize feedback, baseline artifact.

Claude Code (Multi-Agent):

"Create Software Architecture Document with multi-agent review"

Warp Terminal (Context-Aware):

# In Warp AI
"Create architecture baseline with security and testing review"

Factory AI (Droid Orchestration):

"Create SAD with multi-agent review"
# Factory automatically coordinates: architecture-designer → reviewers → synthesizer

Workflow: Primary Author → 4 Parallel Reviewers → Synthesizer → Baseline

Note: Multi-agent orchestration is a strength of Claude Code and Factory AI. Warp provides context-aware guidance.

---

Use Case 5: Run Marketing Campaigns with AI Agents

Problem: Marketing teams lack structured workflows. Content scattered, brand inconsistent, no lifecycle tracking.

Solution: Deploy MMK framework with 37 agents, 23 commands, and 88 templates.

Claude Code:

# Deploy marketing framework
aiwg use marketing

# Start a campaign
/campaign-kickoff "Q1 Product Launch"

# Check campaign status
/marketing-status

---

Use Case 6: Framework Self-Improvement Loop

Problem: Framework needs dogfooding. How do you use SDLC tools to improve SDLC tools?

Solution: Use framework on itself. Generate artifacts, track velocity, iterate.

Current Status: 100% Inception artifact coverage (vision, business case, risks, architecture)

Meta-Validation: If the framework can manage itself, it can manage your project.

---

🗂️ Framework-Scoped Workspace Architecture

NEW: AIWG now supports multiple concurrent frameworks (SDLC, Marketing, Legal, etc.) with automatic routing and complete isolation.

Zero-Friction Multi-Framework Support

The Problem: Traditional process frameworks force you to choose ONE methodology. SDLC for development, Marketing for launches, Legal for compliance - you can't mix them.

The Solution: Framework-scoped workspace management lets you run multiple frameworks simultaneously with zero manual configuration.

# No framework selection needed - routes automatically based on context
"Transition to Elaboration"        → SDLC framework
"Draft launch announcement"         → Marketing framework
"Review contract compliance"        → Legal framework
"Where are we in the project?"     → Active framework

4-Tier Workspace Architecture

Each framework gets its own isolated workspace with 4 tiers:

.aiwg/
├── frameworks/
│   ├── sdlc-complete/
│   │   ├── repo/              → Tier 1: Framework templates, shared docs
│   │   ├── projects/          → Tier 2: Active project artifacts
│   │   │   ├── plugin-system/
│   │   │   └── marketing-site/
│   │   ├── working/           → Tier 3: Temporary multi-agent work
│   │   └── archive/           → Tier 4: Completed projects (by month)
│   ├── marketing-flow/
│   │   ├── repo/
│   │   ├── campaigns/         → Marketing uses "campaigns" not "projects"
│   │   ├── working/
│   │   └── archive/
│   └── legal-review/
│       ├── repo/
│       ├── matters/           → Legal uses "matters" not "projects"
│       ├── working/
│       └── archive/
└── shared/                    → Cross-framework resources

Key Features

1. Automatic Framework Detection

Commands and agents include metadata that automatically routes work to the correct framework:

---
framework: sdlc-complete
output-path: frameworks/sdlc-complete/projects/{project-id}/
---

No manual selection. No configuration files. Just works.

2. Complete Isolation

Each framework writes only to its own workspace. No cross-contamination:

• ✅ SDLC artifacts → .aiwg/frameworks/sdlc-complete/
• ✅ Marketing artifacts → .aiwg/frameworks/marketing-flow/
• ✅ Legal artifacts → .aiwg/frameworks/legal-review/

3. Cross-Framework Reads ("The Magic")

While writes are isolated, reads are unrestricted. This enables novel combinations:

• Marketing reads SDLC use cases → generates user-facing feature docs
• SDLC security reads Marketing personas → tailors threat models to target audience
• Legal reads SDLC architecture → identifies compliance risks in system design

This cross-pollination is where the real value emerges.

4. Plugin Health Monitoring

Check the health of all installed frameworks/add-ons/extensions:

aiwg -status

FRAMEWORKS (2 installed)
┌────────────────┬─────────┬──────────────┬──────────┬─────────────────┐
│ ID             │ Version │ Installed    │ Projects │ Health          │
├────────────────┼─────────┼──────────────┼──────────┼─────────────────┤
│ sdlc-complete  │ 1.0.0   │ 2025-10-18   │ 2        │ ✓ HEALTHY       │
│ marketing-flow │ 1.0.0   │ 2025-10-19   │ 1        │ ✓ HEALTHY       │
└────────────────┴─────────┴──────────────┴──────────┴─────────────────┘

ADD-ONS (1 installed)
┌─────────────────┬─────────┬──────────────┬────────────┬─────────────────┐
│ ID              │ Version │ Installed    │ Framework  │ Health          │
├─────────────────┼─────────┼──────────────┼────────────┼─────────────────┤
│ gdpr-compliance │ 1.0.0   │ 2025-10-18   │ sdlc-comp. │ ✓ HEALTHY       │
└─────────────────┴─────────┴──────────────┴────────────┴─────────────────┘

Use Cases

UC-1: Solo Developer Running Multiple Frameworks

You're building a SaaS product (SDLC) and planning the launch (Marketing):

# Morning: Technical work
"Create Software Architecture Document"    → SDLC framework
"Run security review"                      → SDLC framework

# Afternoon: Marketing work
"Draft launch announcement"                → Marketing framework
"Create content calendar"                  → Marketing framework

# All artifacts organized automatically, no context switching

UC-2: Team Coordination Across Disciplines

Dev team uses SDLC, marketing team uses Marketing framework, both access shared resources:

# Dev team creates feature spec
.aiwg/frameworks/sdlc-complete/projects/v2-release/requirements/feature-spec.md

# Marketing team reads spec and generates launch content
"Read SDLC feature spec and draft launch announcement"
→ Marketing framework reads from SDLC (cross-framework read)
→ Writes to marketing-flow workspace (isolated write)

UC-3: Compliance Add-ons

Install GDPR compliance add-on that extends SDLC framework:

aiwg -install-addon gdpr-compliance

# GDPR templates now available in SDLC workflows
"Run GDPR compliance validation"
→ Uses GDPR add-on templates
→ Writes to SDLC workspace
→ Health monitoring includes GDPR add-on

---

🛠️ Installation & Setup

⚠️ Early Access: This framework is in active development. Expect evolving features and documentation.

Method 1: Claude Code Plugin (Recommended for Claude Code)

Native integration with Claude Code's plugin system. Install modular plugins directly in Claude Code.

Step 1: Add AIWG Marketplace

/plugin marketplace add jmagly/ai-writing-guide

Step 2: Install Plugins

Plugin	Command	Description
sdlc	/plugin install sdlc@aiwg	64 SDLC agents, 97 commands
marketing	/plugin install marketing@aiwg	37 marketing agents
utils	/plugin install utils@aiwg	Core utilities, context regeneration
voice	/plugin install voice@aiwg	Voice profiles for consistent writing
writing	/plugin install writing@aiwg	AI pattern detection, writing validation
hooks	/plugin install hooks@aiwg	Workflow tracing and observability

Step 3: Verify Installation

/plugin list

Benefits of Plugin Installation:

• Native Claude Code integration
• Modular: install only what you need
• Automatic updates via marketplace
• No global npm install required

---

Method 2: npm Install (Recommended for CLI + Multi-Platform)

Global npm install for CLI access and multi-platform deployment:

curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash

Verify installation:

aiwg -version

Auto-updates: CLI auto-updates before every command (always latest version).

---

Method 3: Manual Clone (Development)

Clone repository directly:

git clone https://github.com/jmagly/ai-writing-guide.git ~/.local/share/ai-writing-guide
cd ~/.local/share/ai-writing-guide

Use tools directly:

# Deploy agents
node tools/agents/deploy-agents.mjs --target /path/to/project --mode both

# Scaffold new project
node tools/install/new-project.mjs --name my-project

# Prefill SDLC cards
node tools/cards/prefill-cards.mjs --target artifacts/my-project --team team.yaml --write

---

📋 Prerequisites

Before installing, ensure you have the following requirements. This framework is tested and validated for Claude Code, Warp Terminal, and Factory AI. Support for other platforms is in development.

ℹ️ Technical Notes:

• Rate Limits: Agentic tools handle rate limits and retries automatically. No manual timeout management required.
• Version Control: Document rollback is optional and user-controlled. Enable by committing .aiwg/ artifacts to git, or add .aiwg/ to .gitignore for local-only use.

Required

1. Node.js ≥18.20.8 (LTS: Hydrogen)

Check if you have Node.js:

node --version  # Should show v18.20.8 or higher

Don't have Node.js? Choose your installation method:

📦 macOS (Homebrew)

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js LTS
brew install node@18

Official Homebrew docs →

📦 Linux (NodeSource)

Ubuntu/Debian:

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

Fedora/RHEL:

# Add NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -

# Install Node.js
sudo dnf install -y nodejs

NodeSource installation guide →

📦 Windows (WSL2 Required)

Step 1: Install WSL2

# Run in PowerShell as Administrator
wsl --install

Step 2: Install Node.js in WSL2

# Open WSL2 terminal
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

WSL2 installation guide →

📦 NVM (Node Version Manager) - All Platforms

Install NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Install Node.js 18:

nvm install 18
nvm use 18
nvm alias default 18

Verify:

node --version  # Should show v18.x.x

NVM installation guide →

---

2. AI Platform (Choose One or More)

This framework supports Claude Code, Warp Terminal, and Factory AI. Choose based on your workflow:

Option A: Claude Code (Multi-Agent Orchestration)

Best for: Full SDLC orchestration, multi-agent workflows, artifact generation

Install Claude Code:

1. Download: Visit claude.ai/code
2. Sign up/Login: Create an Anthropic account or login
3. Install CLI: Follow platform-specific instructions (macOS, Linux, Windows)

Verify Installation:

claude --version  # Should show Claude Code version

Claude Code Quick Start → | Documentation →

---

Option B: Warp Terminal (Terminal-Native Workflows)

Best for: Command-line workflows, terminal-native AI, lightweight integration

Install Warp Terminal:

1. Download: Visit warp.dev
2. Sign up/Login: Create a Warp account or login
3. Install: Follow platform-specific instructions (macOS, Linux)

Verify Installation:

# Warp is installed if it opens successfully
# No separate CLI to verify

Warp Terminal Quick Start → | Documentation →

---

Option C: Factory AI (Custom Droids)

Best for: Custom droid workflows, native Factory format, AGENTS.md-based configuration

Install Factory AI:

1. Download: Visit factory.ai
2. Install CLI: curl -fsSL https://app.factory.ai/cli | sh
3. Sign up/Login: Create a Factory account or login

Verify Installation:

factory --version  # Should show Factory CLI version
droid .            # Launch Factory in current directory

Factory AI Quick Start → | Documentation →

---

Option D: Use Multiple Platforms (Recommended)

Get the best of all platforms:

• Claude Code: Multi-agent orchestration, artifact generation
• Warp Terminal: Command-line workflows, terminal-native AI
• Factory AI: Custom droid workflows, native Factory format
• Cursor: IDE-native rules, native AGENTS.md support
• Codex: OpenAI's code assistant, prompts format

# Deploy to all platforms
aiwg use sdlc                      # Claude Code (default)
aiwg use sdlc --provider warp      # Warp Terminal
aiwg use sdlc --provider factory   # Factory AI
aiwg use sdlc --provider cursor    # Cursor IDE
aiwg use sdlc --provider openai    # OpenAI Codex

---

Platform Support Status

Platform	Status	Integration	Notes
Claude Code	✅ Tested & Validated	Plugin or .claude/agents/*.md	Multi-agent orchestration, native plugins
GitHub Copilot	✅ Tested & Validated	.github/agents/*.yaml	copilot-instructions.md
Warp Terminal	✅ Tested & Validated	Single-file (WARP.md)	Terminal-native workflows
Factory AI	✅ Tested & Validated	.factory/droids/*.md	Native droid format, AGENTS.md
OpenCode	✅ Tested & Validated	.opencode/agent/	AGENTS.md
Cursor	✅ Tested & Validated	.cursor/rules/*.mdc	Native rules format, AGENTS.md
OpenAI/Codex	✅ Tested & Validated	.codex/agents/	Native prompts format, AGENTS.md
Windsurf	🟡 Experimental	.windsurfrules	Should work, not validated
Zed	🟡 Experimental	Claude-compatible	Should work, not validated

Want to help? We're actively seeking beta testers for other platforms! Open a discussion if you're interested.

---

Operating Systems

Fully Supported:

• ✅ macOS (Intel + Apple Silicon)
• ✅ Linux (Ubuntu, Debian, Fedora, Arch, RHEL)
• ✅ WSL2 (Windows Subsystem for Linux)

Not Supported:

• ❌ Native Windows (PowerShell/CMD) — Use WSL2 instead

---

Optional (Recommended)

Git: Required for aiwg -new project scaffolding and version control.

# Check if you have Git
git --version

# Install Git (if needed)
# macOS (Homebrew)
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Fedora/RHEL
sudo dnf install git

---

Quick Compatibility Check

Run this command to verify all prerequisites:

# Check Node.js version
node --version && echo "✅ Node.js installed" || echo "❌ Node.js missing"

# Check Claude Code (if using)
claude --version && echo "✅ Claude Code installed" || echo "ℹ️ Claude Code not installed"

# Check Warp Terminal (if using)
# Open Warp Terminal and verify it launches successfully

# Check Factory AI (if using)
factory --version && echo "✅ Factory AI installed" || echo "ℹ️ Factory AI not installed"

# Check Git (optional)
git --version && echo "✅ Git installed" || echo "ℹ️ Git optional (needed for aiwg -new)"

All checks passed? You're ready! Jump to installation →

Missing something? Expand the relevant section above for installation instructions.

---

📚 Documentation

Getting Started

• Quick Start Guide — Context selection for different tasks
• Installation Guide — Detailed setup instructions
• CLI Reference — All aiwg commands

Platform Integration

• Claude Code Quick Start — 5-10 minute setup for Claude Code
• Warp Terminal Quick Start — 3-5 minute setup for Warp Terminal
• Warp Terminal Integration Guide — Comprehensive Warp documentation
• Factory AI Quick Start — 5-10 minute setup for Factory AI
• Cursor Quick Start — 5-10 minute setup for Cursor IDE
• Codex Quick Start — 5-10 minute setup for OpenAI Codex
• Cross-Platform Configuration — Understanding the WARP.md → CLAUDE.md symlink

Writing Quality

• Voice Framework — Voice profiles for consistent, authentic writing
• Voice Skills — Apply, create, blend, analyze voices
• Core Philosophy — Fundamental writing principles
• Examples — Before/after rewrites
• Quick Reference — Fast validation checklist

SDLC Framework

• Framework Overview — Complete lifecycle guide
• Agent Catalog — All 64 SDLC agents
• Command Reference — All 97 workflow commands
• Template Library — 172 artifact templates
• Phase Workflows — Inception → Transition
• Natural Language Guide — 70+ supported phrases

Media/Marketing Kit (MMK)

• Framework Overview — Complete marketing lifecycle guide
• Agent Catalog — All 37 marketing agents
• Command Reference — All 23 marketing commands
• Template Library — 103 templates in 15 categories
• Lifecycle Guide — Strategy → Analysis phases

Workspace Management

• Workspace Architecture — Multi-framework support explained
• Workspace Tools — Component documentation
• Migration Guide — Legacy to framework-scoped migration
• Plugin Health — aiwg -status usage

Production-Grade Features

• Production-Grade Guide — Research-backed reliability patterns
• Agent Design Bible — 10 Golden Rules for agent design
• @-Mention Traceability — Wire, validate, lint @-mentions
• Deploy Generators — Docker, K8s, Compose templates
• Research References — REF-001 (Production-Grade) + REF-002 (Failure Modes)

MCP Server (Model Context Protocol)

AIWG includes an MCP server for programmatic integration:

# Start MCP server (stdio transport)
aiwg mcp serve

# Install config for Claude Desktop or Cursor
aiwg mcp install claude
aiwg mcp install cursor

# View MCP info
aiwg mcp info

MCP Tools: workflow-run, artifact-read, artifact-write, template-render, agent-list

MCP Prompts: decompose-task, parallel-execution, recovery-protocol (auto-integrated)

• MCP Specification Research — MCP 2025-11-25 implementation details

Sponsors & Support

• Our Sponsors — Organizations making AIWG possible

Advanced Topics

• Multi-Agent Orchestration — Parallel reviews and synthesis
• Orchestrator Architecture — How workflows coordinate
• Multi-Platform Support — Claude vs OpenAI differences
• Development Guide — Advanced slash command patterns

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Contributions

Found a new AI pattern? Open an issue with examples.

Have a better rewrite? Submit a PR to examples/ with before/after.

Want to add an agent? Use docs/agents/agent-template.md as a starting point.

Development Workflow

1. Fork and clone:

   git clone https://github.com/your-username/ai-writing-guide.git
   cd ai-writing-guide

2. Create feature branch:

   git checkout -b feat/your-feature-name

3. Make changes and test:

   # Run markdown linting
   npm exec markdownlint-cli2 "**/*.md"
   
   # Test agent deployment
   node tools/agents/deploy-agents.mjs --target /tmp/test-project --dry-run

4. Commit using conventions:

   git commit -m "feat(agents): add database-optimizer agent"

5. Push and create PR:

   git push origin feat/your-feature-name

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, refactor, test, chore, ci

Scopes: agents, commands, templates, tools, docs, intake, flows

Example:

feat(agents): add cloud-architect specialized agent

Created AWS/Azure/GCP infrastructure design agent with:
- Multi-cloud IaC design (Terraform/CloudFormation)
- Cost optimization strategies
- Auto-scaling and multi-region deployments

Closes #123

Full contributing guide →

---

💬 Community & Support

Get Help

• 🌐 Website: aiwg.io
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Usage Guide | SDLC README

Join Our Community

• 💬 Discord: Join Server
• 📱 Telegram: Join Group
• 🗨️ GitHub Discussions: Community Forum

Stay Updated

• ⭐ Star this repo to follow development
• 👀 Watch releases for new features and templates

---

💡 Usage Notes

AIWG is optimized for token efficiency through modular context loading and path-scoped rules. Most users on Claude Pro or similar plans will have no issues with normal usage.

Account Type	Suitability
Claude Pro / Team	✅ Recommended
API Pay-as-you-go	✅ Works well with cost monitoring
Free tiers	⚠️ May hit rate limits on heavy workflows

Tips: Start with individual workflows before running full SDLC phases. Use --interactive mode to control generation scope.

---

📄 License & Disclaimer

MIT License

Free to use, modify, and distribute. Full text: LICENSE

MIT License

Copyright (c) 2025 Joseph Magly

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Important Disclaimers

No Warranty

THE SOFTWARE IS PROVIDED "AS IS", without warranty of any kind. The authors make no guarantees about:

• Accuracy of generated artifacts
• Fitness for any particular purpose
• Absence of bugs or logic errors
• API cost predictions
• Compatibility with all platforms

Not Professional Advice

This framework does not provide:

• Legal advice (compliance guidance is informational only)
• Security audit services (templates are starting points, not guarantees)
• Financial consulting (ROI estimates are illustrative)
• Professional liability coverage

Always consult qualified professionals for legal, security, and compliance requirements.

User Responsibility

You are responsible for:

• Reviewing all generated content before use
• Validating compliance with your specific regulations
• Testing in non-production environments first
• Monitoring and controlling API costs
• Maintaining backups of critical data
• Understanding licensing of generated artifacts (MIT applies to framework, but your outputs are yours)

Experimental Status

This framework is in active development (Phase 1: Validation). Expect:

• Breaking changes to agents, commands, templates
• Incomplete documentation
• Bugs and unexpected behavior
• Rate limit issues
• API cost volatility

Not recommended for:

• Production-critical projects without thorough testing
• Regulated industries without legal review
• Budget-constrained accounts (pay-as-you-go)
• Time-sensitive deliverables (troubleshooting may take days)

Data & Privacy

• No data collection: Framework processes everything locally
• No telemetry: No analytics, tracking, or usage reporting
• User artifacts: You own everything generated (MIT license does not claim your outputs)
• Third-party services: Claude Code/OpenAI terms apply to API usage

Read Privacy Policy → | Read Terms of Use →

Cost Responsibility

API usage costs are your responsibility. The framework does not:

• Track or limit your spending
• Provide cost alerts or budgets
• Guarantee cost estimates
• Refund unexpected charges

Monitor your usage via your AI provider's dashboard. Set budget alerts if available.

---

Known Limitations

Current Limitations (will improve over time):

• ⚠️ Fully tested with Claude Code, Warp Terminal, and Factory AI (other platforms experimental)
• ⚠️ English-only templates and agents
• ⚠️ No cost tracking or budget enforcement
• ⚠️ Context window limits not validated (>200k tokens)
• ⚠️ Only two process frameworks currently available (Writing Quality + SDLC Complete)

Report Issues: GitHub Issues

---

❤️ Sponsors

AIWG would not be possible without the generous support of our sponsors.

Roko Network The Temporal Layer for Web3 Building enterprise-grade timing infrastructure for blockchain applications. Roko Network enables developers to create decentralized systems with nanosecond-level precision—solving one of distributed computing's hardest problems.

Selfient No-Code Smart Contracts for Everyone Democratizing Web3 by making blockchain-based agreements accessible to all. Selfient empowers creators, freelancers, and businesses to create enforceable smart contracts without writing a single line of code.

Integro Labs AI-Powered Automation Solutions Harnessing the transformative potential of AI and blockchain to shape digital automation. Integro Labs delivers custom solutions that help individuals and businesses thrive in the age of intelligent systems.

Interested in sponsoring? Contact us to learn how your organization can support open-source AI tooling.

---

🙏 Acknowledgments

Built with inspiration from:

• Writing Quality: Hemingway Editor, Grammarly
• SDLC Practices: Rational Unified Process (RUP), ITIL, Agile methodologies
• Agent Patterns: Multi-agent orchestration, collaborative AI research
• OSS Projects: React, Vue.js, Next.js, Tailwind CSS (README design inspiration)
• Skill Creation: Skill Seekers (MIT) — Documentation-to-skill conversion

Special thanks to the teams at Anthropic (Claude Code), Warp (Warp Terminal), and Factory AI for building the platforms that make this possible.

---

⬆ Back to Top

Made with ☕ and 🤖 by Joseph Magly

Questions? Open an issue or start a discussion