aiwg 2024.12.2 → 2024.12.4

package/CLAUDE.md

@@ -56,9 +56,12 @@ Use `@path/to/file.md` in your message to load specific documentation:
 | Platform | Agent Location | Command |
 |----------|----------------|---------|
 | Claude Code | `.claude/agents/` | `aiwg -deploy-agents` |
+| GitHub Copilot | `.github/agents/` | `aiwg -deploy-agents --provider copilot` |
 | Warp Terminal | `WARP.md` | Symlinked to CLAUDE.md |
 | Factory AI | `.factory/droids/` | `aiwg -deploy-agents --provider factory` |
-| OpenAI/Codex | `.codex/agents/` | `aiwg -deploy-agents --provider openai` |
+| OpenCode | `.opencode/agent/` | `aiwg -deploy-agents --provider opencode` |
+| Cursor | `.cursor/rules/` | `aiwg -deploy-agents --provider cursor` |
+| OpenAI/Codex | `~/.codex/skills/` | `aiwg -deploy-agents --provider codex` |
 
 ## Writing Principles
 
@@ -134,3 +137,4 @@ npm exec markdownlint-cli2 "**/*.md"
 ---
 
 <!-- TEAM DIRECTIVES: Add project-specific guidance below this line -->
+

package/README.md

@@ -1,19 +1,25 @@
 <div align="center">
 
-# 🎯 AIWG - AI Workflow Guide
+# AIWG – Agentic AI Workflow Guide
 
-### Build like a pro. Write like a human.
+Modular toolkit for AI-powered SDLC, marketing, and content workflows.
 
-**A modular framework toolkit for AI-powered software development, marketing automation, and content quality**
+```bash
+npm i -g aiwg        # install globally
+aiwg use sdlc        # deploy SDLC framework
+```
+
+[![npm version](https://img.shields.io/npm/v/aiwg/latest?label=npm&color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
+[![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm&style=flat-square)](https://www.npmjs.com/package/aiwg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/jmagly/ai-writing-guide?style=flat-square)](https://github.com/jmagly/ai-writing-guide/stargazers)
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node Version](https://img.shields.io/badge/node-%3E%3D18.20.8-brightgreen)](https://nodejs.org)
-[![GitHub Stars](https://img.shields.io/github/stars/jmagly/ai-writing-guide?style=social)](https://github.com/jmagly/ai-writing-guide/stargazers)
+[**Get Started**](#-quick-start) · [**Documentation**](#-documentation) · [**Examples**](examples/) · [**Contributing**](#-contributing) · [**Community**](#-community--support)
 
-[**Get Started**](#-quick-start) · [**Prerequisites**](#-prerequisites) · [**Documentation**](#-documentation) · [**Examples**](examples/) · [**Contributing**](#-contributing) · [**Community**](#-community--support)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/BuAusFMxdA)
+[![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white&style=flat-square)](https://t.me/+oJg9w2lE6A5lOGFh)
 
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/BuAusFMxdA)
-[![Telegram](https://img.shields.io/badge/Telegram-Join-26A5E4?logo=telegram&logoColor=white)](https://t.me/+oJg9w2lE6A5lOGFh)
+🌐 **Live demo & docs:** [https://jmagly.github.io/ai-writing-guide](https://jmagly.github.io/ai-writing-guide)
 
 </div>
 
@@ -21,38 +27,37 @@
 
 ## 🚀 Quick Start
 
-> **📋 Prerequisites:** Node.js ≥18.0.0 and an AI platform (Claude Code, Warp Terminal, or Factory AI). [See detailed setup instructions →](#-prerequisites)
-
-### Option 1: npm (Recommended)
+> **Prerequisites:** Node.js ≥18.0.0 and an AI platform (Claude Code, GitHub Copilot, Warp Terminal, or others)
 
 ```bash
+# Install
 npm install -g aiwg
-```
 
-### Option 2: Bash Script (Legacy)
+# Activate on your project
+cd your-project
+aiwg use sdlc
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash
+# Or scaffold a new project with everything set up
+aiwg -new my-project
 ```
 
 <details>
-<summary><strong>Bleeding Edge Mode</strong></summary>
-
-After installing via npm, you can switch to bleeding edge (latest from main branch):
+<summary><strong>More installation options</strong></summary>
 
+**Bash Script (Legacy):**
 ```bash
-# Switch to edge channel (tracks main branch)
-aiwg --use-main
-
-# Switch back to stable (npm releases)
-aiwg --use-stable
+curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash
 ```
 
-Edge mode is for power users who want the latest features before they're released.
+**Bleeding Edge Mode:**
+```bash
+aiwg --use-main      # Track main branch
+aiwg --use-stable    # Back to npm releases
+```
 
 </details>
 
-**Activate on your project** — Choose your framework:
+**Choose your framework:**
 
 ```bash
 cd your-project
@@ -77,6 +82,15 @@ 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
 ```
@@ -137,9 +151,9 @@ cd my-awesome-project
 </tr>
 </table>
 
-### 🔧 **Production-Grade Reliability**
+### 🔧 **Reliability Patterns**
 
-**Research-backed patterns for enterprise-grade AI workflows.**
+**Research-backed patterns for robust AI workflows.**
 
 <table>
 <tr>
@@ -153,7 +167,7 @@ cd my-awesome-project
 <td width="50%">
 
 - ✅ **Failure Mode Mitigations** — Address 4 LLM failure archetypes
-- ✅ **Deploy Generators** — Production-ready Docker/K8s configs
+- ✅ **Deploy Generators** — Docker/K8s config generation
 - ✅ **Evals Framework** — Automated agent behavior testing
 
 </td>
@@ -183,6 +197,31 @@ cd my-awesome-project
 </tr>
 </table>
 
+### 🧪 **Testing Quality Addon**
+
+**Enforce TDD. Validate quality.** Research-backed testing enforcement, quality metrics, and automation.
+
+<table>
+<tr>
+<td width="50%">
+
+- ✅ **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
+
+</td>
+<td width="50%">
+
+- ✅ **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
+
+</td>
+</tr>
+</table>
+
+**Research Foundation:** Kent Beck (TDD), Google Testing Blog (80% coverage), FlaKat (flaky detection), UTRefactor (test maintenance)
+
 ---
 
 ## 🎬 See It In Action
@@ -282,9 +321,13 @@ aiwg/
 │   │   ├── 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)
+│   ├── 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
@@ -903,12 +946,16 @@ 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
 
 ```bash
 # 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
 ```
 
 ---
@@ -920,8 +967,8 @@ aiwg use sdlc --provider factory   # Factory AI
 | **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 |
-| **OpenAI/Codex** | 🟡 Experimental | `--provider openai` | Functional but not fully tested |
-| **Cursor** | 🟡 Experimental | Claude-compatible | Should work, not validated |
+| **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 |
 
@@ -1003,6 +1050,8 @@ git --version && echo "✅ Git installed" || echo "ℹ️ Git optional (needed f
 - [**Warp Terminal Quick Start**](docs/integrations/warp-terminal-quickstart.md) — 3-5 minute setup for Warp Terminal
 - [**Warp Terminal Integration Guide**](docs/integrations/warp-terminal.md) — Comprehensive Warp documentation
 - [**Factory AI Quick Start**](docs/integrations/factory-quickstart.md) — 5-10 minute setup for Factory AI
+- [**Cursor Quick Start**](docs/integrations/cursor-quickstart.md) — 5-10 minute setup for Cursor IDE
+- [**Codex Quick Start**](docs/integrations/codex-quickstart.md) — 5-10 minute setup for OpenAI Codex
 - [**Cross-Platform Configuration**](docs/integrations/cross-platform-config.md) — Understanding the WARP.md → CLAUDE.md symlink
 
 ### Writing Quality
@@ -1172,50 +1221,17 @@ Closes #123
 
 ---
 
-## ⚠️ Cost Considerations
-
-**IMPORTANT:** This framework generates extensive AI interactions. Understand your costs before deploying.
-
-### Usage Characteristics
-
-**Document Generation Volume:**
-- Single workflow: 5,000-15,000 words (intake, SAD, reviews, synthesis)
-- Multi-agent pattern: 3-5x token multiplier (parallel reviews)
-- Full Inception phase: ~50,000-100,000 words total output
-- Iteration cycles: 10,000-30,000 words per iteration
-
-**Typical Monthly Usage** (varies widely):
-- **Light** (1-2 workflows/week): 40,000-120,000 words → ~$10-20/month
-- **Moderate** (10-20 workflows/month): 150,000-300,000 words → **$20-50/month**
-- **Heavy** (daily workflows, full SDLC): 500,000+ words → **$50-150+/month**
-
-### Account Requirements
-
-| Account Type | Suitability | Notes |
-|--------------|-------------|-------|
-| **Claude Free** | ❌ Not Suitable | Daily message limits hit quickly (5-10 messages) |
-| **Claude Pro** | ✅ **Recommended** | Higher limits, suitable for moderate usage |
-| **Claude Team/Enterprise** | ✅ Best | Highest limits, team collaboration, no rate throttling |
-| **API Pay-as-you-go** | ⚠️ Use with Caution | Can be expensive without cost controls ($50-200+/month) |
-
-### Cost Mitigation Strategies
-
-1. **Start Small:** Test with 1-2 use cases before full deployment
-2. **Use Selectively:** Not every project needs full SDLC artifacts
-3. **Manual Review:** Edit generated drafts instead of regenerating
-4. **Monitor Usage:** Track costs weekly, set budget alerts if using API
-5. **Skip Optional Workflows:** Only run required artifacts for your profile
+## 💡 Usage Notes
 
-### Your Mileage May Vary
+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.
 
-Actual costs depend on:
-- Codebase size (larger = more tokens)
-- Project complexity (more complex = longer artifacts)
-- Revision frequency (regeneration costs add up)
-- Account tier and rate limits
-- Whether you hit rate limits (retry costs)
+| 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 |
 
-**Bottom Line:** Budget $20-50/month for moderate use. Enterprise teams may see $100-500+/month depending on scale.
+**Tips:** Start with individual workflows before running full SDLC phases. Use `--interactive` mode to control generation scope.
 
 ---
 

package/agentic/code/addons/aiwg-utils/README.md

@@ -4,6 +4,27 @@ Core meta-utilities for AIWG management. This addon is automatically installed w
 
 ## Commands
 
+### Deployment Management
+
+#### `/aiwg-refresh`
+
+Update AIWG CLI and redeploy frameworks/tools to current project without leaving the session.
+
+```bash
+/aiwg-refresh                       # Check status only
+/aiwg-refresh --update-cli --all    # Update CLI and redeploy everything
+/aiwg-refresh --sdlc                # Redeploy SDLC framework only
+/aiwg-refresh --provider factory    # Switch to Factory AI deployment
+/aiwg-refresh --dry-run             # Preview without executing
+```
+
+**Use cases:**
+
+- Get latest features after AIWG updates
+- Restore canonical content after manual edits
+- Switch deployment platform (Claude → Factory)
+- Ensure consistency after branch switches
+
 ### Context Regeneration
 
 #### `/aiwg-regenerate`

package/agentic/code/addons/aiwg-utils/commands/aiwg-refresh.md

@@ -0,0 +1,307 @@
+---
+name: aiwg-refresh
+description: Update AIWG CLI and redeploy frameworks/tools to current project without leaving the session
+args: "[--update-cli] [--all] [--sdlc] [--marketing] [--utils] [--provider <name>] [--force] [--dry-run]"
+---
+
+# Refresh AIWG Deployment
+
+Update the AIWG CLI and/or redeploy frameworks, agents, commands, and tools to the current
+project without leaving the agentic session.
+
+## Use Cases
+
+- **After AIWG updates**: Get latest framework features without restarting
+- **After switching branches**: Ensure deployed content matches expectations
+- **After manual edits**: Restore canonical AIWG content
+- **Provider switch**: Redeploy for different platform (Claude → Factory)
+
+## Parameters
+
+| Flag | Description |
+|------|-------------|
+| `--update-cli` | Update AIWG CLI to latest version before redeploying |
+| `--all` | Redeploy all installed frameworks |
+| `--sdlc` | Redeploy SDLC framework only |
+| `--marketing` | Redeploy Marketing framework only |
+| `--utils` | Redeploy aiwg-utils addon only |
+| `--provider <name>` | Target platform: claude, factory, openai, cursor, warp (default: auto-detect) |
+| `--force` | Force redeploy even if already up-to-date |
+| `--dry-run` | Show what would be done without executing |
+
+## Execution Steps
+
+### Step 1: Show Current Status
+
+Run status check and report current state:
+
+```bash
+aiwg -status
+```
+
+Report:
+
+```text
+AIWG Refresh - Current Status
+==============================
+
+CLI Version: 1.2.3 (stable channel)
+Workspace: /path/to/project/.aiwg
+
+Installed Frameworks:
+  - sdlc-complete v1.0.0 (58 agents, 48 commands)
+  - aiwg-utils v1.0.0 (3 agents, 25 commands)
+
+Platform: Claude Code (.claude/)
+  - Agents: 61 deployed
+  - Commands: 73 deployed
+```
+
+### Step 2: Update CLI (if --update-cli)
+
+If `--update-cli` flag is set:
+
+```bash
+aiwg -update
+```
+
+Report update status:
+
+```text
+Checking for updates...
+  Current: 1.2.3
+  Latest:  1.2.5
+
+Updating AIWG CLI...
+✓ Updated to v1.2.5
+
+Changes in v1.2.5:
+  - New mutation-analyst agent
+  - Testing-quality addon
+  - Bug fixes
+```
+
+If already up-to-date:
+
+```text
+AIWG CLI is up-to-date (v1.2.3)
+```
+
+### Step 3: Determine What to Redeploy
+
+Based on flags, determine scope:
+
+| Flags | Action |
+|-------|--------|
+| No flags | Show status only, prompt for action |
+| `--all` | Redeploy all installed frameworks |
+| `--sdlc` | Redeploy sdlc-complete only |
+| `--marketing` | Redeploy media-marketing-kit only |
+| `--utils` | Redeploy aiwg-utils addon only |
+| Multiple | Redeploy specified frameworks |
+
+If no framework flags and not `--dry-run`, ask user:
+
+```text
+What would you like to refresh?
+
+[1] All frameworks (sdlc-complete, aiwg-utils)
+[2] SDLC framework only
+[3] Utils addon only
+[4] Just show status (no changes)
+
+Choice:
+```
+
+### Step 4: Detect Target Platform
+
+If `--provider` not specified, auto-detect:
+
+1. Check existing deployments:
+   - `.claude/agents/` exists → claude
+   - `.factory/droids/` exists → factory
+   - `.codex/agents/` exists → openai
+   - `.cursor/rules/` exists → cursor
+
+2. If multiple detected, ask user:
+
+   ```text
+   Multiple platforms detected:
+   [1] Claude Code (.claude/)
+   [2] Factory AI (.factory/)
+
+   Which platform to refresh?
+   ```
+
+3. If none detected, default to claude
+
+Report:
+
+```text
+Target platform: Claude Code
+Deployment paths:
+  - Agents: .claude/agents/
+  - Commands: .claude/commands/
+```
+
+### Step 5: Execute Redeploy
+
+For each framework to deploy:
+
+```bash
+# SDLC Framework
+aiwg use sdlc --provider <platform> --force
+
+# Marketing Framework
+aiwg use marketing --provider <platform> --force
+
+# Utils (included with sdlc)
+# No separate command needed
+```
+
+**If `--dry-run`:**
+Show commands without executing:
+
+```text
+Dry Run - Would execute:
+========================
+
+1. aiwg use sdlc --provider claude --force
+   → Deploy 58 agents to .claude/agents/
+   → Deploy 48 commands to .claude/commands/
+
+2. aiwg use marketing --provider claude --force
+   → Deploy 37 agents to .claude/agents/
+   → Deploy 20 commands to .claude/commands/
+
+No changes made (dry run mode)
+```
+
+**Progress Reporting:**
+
+```text
+Refreshing AIWG Deployment
+==========================
+
+[1/2] Deploying sdlc-complete...
+  → Copying 58 agents...
+  → Copying 48 commands...
+  → Copying 12 templates...
+  ✓ sdlc-complete deployed
+
+[2/2] Deploying aiwg-utils...
+  → Copying 3 agents...
+  → Copying 25 commands...
+  ✓ aiwg-utils deployed
+```
+
+### Step 6: Verify Deployment
+
+After deployment, verify:
+
+```bash
+# Count deployed assets
+ls .claude/agents/*.md 2>/dev/null | wc -l
+ls .claude/commands/*.md 2>/dev/null | wc -l
+```
+
+Report:
+
+```text
+Verification
+============
+
+Deployed Assets:
+  - Agents: 95 files
+  - Commands: 93 files
+
+Platform Files:
+  - CLAUDE.md: Present
+  - .claude/settings.local.json: Present
+
+All assets deployed successfully!
+```
+
+### Step 7: Summary Report
+
+```text
+AIWG Refresh Complete
+=====================
+
+CLI:
+  Version: 1.2.5 (updated from 1.2.3)
+
+Frameworks Deployed:
+  ✓ sdlc-complete v1.0.0 (58 agents, 48 commands)
+  ✓ aiwg-utils v1.0.0 (3 agents, 25 commands)
+
+Platform: Claude Code
+  - .claude/agents/: 61 files
+  - .claude/commands/: 73 files
+
+New capabilities available:
+  - /setup-tdd - TDD enforcement setup
+  - /flow-test-strategy-execution - Test execution workflow
+  - mutation-analyst agent - Test quality analysis
+
+Session ready - new features are now available!
+```
+
+## Examples
+
+```bash
+# Check status only
+/aiwg-refresh
+
+# Update CLI and redeploy everything
+/aiwg-refresh --update-cli --all
+
+# Just redeploy SDLC framework
+/aiwg-refresh --sdlc
+
+# Switch to Factory AI deployment
+/aiwg-refresh --all --provider factory
+
+# Preview what would happen
+/aiwg-refresh --all --dry-run
+
+# Force refresh even if up-to-date
+/aiwg-refresh --all --force
+```
+
+## Natural Language Triggers
+
+This command should activate when user says:
+
+- "refresh aiwg" / "update aiwg"
+- "redeploy frameworks" / "redeploy agents"
+- "get latest aiwg features"
+- "update my aiwg tools"
+- "sync aiwg deployment"
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| AIWG CLI not found | Error: "AIWG CLI not installed. Run: curl -fsSL ... \| bash" |
+| Network error on update | Warn and continue with existing version |
+| Framework not installed | Offer to install: "SDLC not installed. Install now? [y/N]" |
+| Permission denied | Error with specific file/directory that failed |
+| Invalid provider | Error listing valid providers |
+
+## Post-Refresh Recommendations
+
+After refresh, suggest:
+
+```text
+Recommended next steps:
+1. Review new features: aiwg -help
+2. Check framework docs: /aiwg-kb sdlc
+3. Run health check: aiwg doctor
+```
+
+## References
+
+- @docs/development/file-placement-guide.md - Correct file placement workflow
+- @agentic/code/addons/aiwg-utils/commands/aiwg-regenerate.md - Context file regeneration
+- @docs/CLI_USAGE.md - Full CLI documentation

package/agentic/code/addons/aiwg-utils/manifest.json

@@ -34,6 +34,7 @@
     "prompts": "prompts/"
   },
   "commands": [
+    "aiwg-refresh",
     "aiwg-regenerate",
     "aiwg-regenerate-claude",
     "aiwg-regenerate-warp",