aiwg

v2024.12.4

Published

12 days ago

Modular agentic framework for AI-powered SDLC, marketing automation, and workflow orchestration

0High
0Medium
0Low

aiwg agentic-ai claude-skills mcp-server model-context-protocol ai-writing ai-sdlc claude-desktop cursor-ide factory-ai skill-seekers ai-agents workflow-automation sdlc-framework

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)

# 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

Bash Script (Legacy):

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

Bleeding Edge Mode:

aiwg --use-main      # Track main branch
aiwg --use-stable    # Back to npm releases

Choose your framework:

cd your-project

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

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

# Deploy all frameworks
aiwg use all

# 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

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.

✅ 53 SDLC agents — Requirements, architecture, testing, security, deployment
✅ 48 workflow commands — Intake, phase gates, risk management, compliance
✅ 156 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
✅ 88 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

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

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

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/ (53)                  → Requirements, architecture, testing, security, DevOps
│   │   ├── commands/ (48)                → Intake, phase gates, deployments, compliance
│   │   ├── templates/ (156)              → 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/ (88)               → 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: One-Line Install (Recommended)

Install to ~/.local/share/ai-writing-guide and activate CLI:

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 2: Manual Clone

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:

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

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 →

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 →

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:

Download: Visit claude.ai/code
Sign up/Login: Create an Anthropic account or login
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:

Download: Visit warp.dev
Sign up/Login: Create a Warp account or login
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:

Download: Visit factory.ai
Install CLI: curl -fsSL https://app.factory.ai/cli | sh
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 | Multi-file (.claude/agents/.md) | Multi-agent orchestration | | Warp Terminal | ✅ Tested & Validated | Single-file (WARP.md) | Terminal-native workflows | | Factory AI | ✅ Tested & Validated | Custom droids (.factory/droids/.md) | Native droid format, AGENTS.md | | Cursor | ✅ Tested & Validated | MDC rules (.cursor/rules/*.mdc) | Native rules format, AGENTS.md | | OpenAI/Codex | ✅ Tested & Validated | --provider openai | Native prompts format, AGENTS.md | | Windsurf | 🟡 Experimental | Claude-compatible | 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 53 SDLC agents
Command Reference — All 48 workflow commands
Template Library — 156 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 — 88 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

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

Fork and clone:

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

Create feature branch:
```
git checkout -b feat/your-feature-name
```

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

Commit using conventions:

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

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

🙏 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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AIWG – Agentic AI Workflow Guide

🚀 Quick Start

✨ What You Get

🏗️ SDLC Complete Framework

📣 Media/Marketing Kit (MMK)

🔧 Reliability Patterns

📝 Writing Quality Addon

🧪 Testing Quality Addon

🎬 See It In Action

Voice Framework: Same Content, Different Voices

SDLC Workflow: Inception → Production

📦 What's Inside

Architecture Overview

Agent Catalog Highlights

🎯 Who Is This For?

👤 Solo Developers

👥 Small Teams (2-10)

🏢 Enterprise Teams

🧩 Use Cases

Use Case 1: Apply Consistent Voice Across Content

Use Case 2: Deploy Full SDLC Framework

Use Case 3: Generate Intake From Existing Codebase

Use Case 4: Multi-Agent Architecture Review

Use Case 5: Run Marketing Campaigns with AI Agents

Use Case 6: Framework Self-Improvement Loop

🗂️ Framework-Scoped Workspace Architecture

Zero-Friction Multi-Framework Support

4-Tier Workspace Architecture

Key Features

Use Cases

🛠️ Installation & Setup

Method 1: One-Line Install (Recommended)

Method 2: Manual Clone

📋 Prerequisites

Required

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

2. AI Platform (Choose One or More)

Platform Support Status

Operating Systems

Optional (Recommended)

Quick Compatibility Check

📚 Documentation

Getting Started

Platform Integration

Writing Quality

SDLC Framework

Media/Marketing Kit (MMK)

Workspace Management

Production-Grade Features

MCP Server (Model Context Protocol)

Advanced Topics

🤝 Contributing

Quick Contributions

Development Workflow

Commit Message Format

💬 Community & Support

Get Help

Join Our Community

Stay Updated

💡 Usage Notes

📄 License & Disclaimer

MIT License

Important Disclaimers

No Warranty

Not Professional Advice

User Responsibility

Experimental Status

Data & Privacy

Cost Responsibility

Known Limitations

🙏 Acknowledgments