aiwg 2024.12.2 → 2024.12.3

package/CLAUDE.md

@@ -134,3 +134,4 @@ npm exec markdownlint-cli2 "**/*.md"
 ---
 
 <!-- TEAM DIRECTIVES: Add project-specific guidance below this line -->
+

package/README.md

@@ -1,58 +1,63 @@
 <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 demo            # try it in < 2 minutes
+```
 
+[![npm version](https://img.shields.io/npm/v/aiwg/latest?label=npm&color=CB3837&logo=npm)](https://www.npmjs.com/package/aiwg)
+[![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm)](https://www.npmjs.com/package/aiwg)
 [![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) · [**Prerequisites**](#-prerequisites) · [**Documentation**](#-documentation) · [**Examples**](examples/) · [**Contributing**](#-contributing) · [**Community**](#-community--support)
+[**Get Started**](#-quick-start) · [**Documentation**](#-documentation) · [**Examples**](examples/) · [**Contributing**](#-contributing) · [**Community**](#-community--support)
 
 [![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>
 
 ---
 
 ## 🚀 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, Warp Terminal, or Factory AI)
 
 ```bash
+# Install
 npm install -g aiwg
-```
 
-### Option 2: Bash Script (Legacy)
+# Try the demo (creates ~/aiwg-demo with everything set up)
+aiwg demo
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash
+# Or activate on your existing project
+cd your-project
+aiwg use sdlc
 ```
 
 <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
@@ -137,9 +142,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 +158,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>
@@ -1172,50 +1177,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/frameworks/sdlc-complete/agents/README.md

@@ -1,7 +1,5 @@
 # SDLC Agents
 
-## Overview
-
 Specialized agents that coordinate lifecycle work: orchestration, governance, security, privacy, traceability, and
 reliability.
 

package/agentic/code/frameworks/sdlc-complete/agents/security-architect.md

@@ -40,3 +40,13 @@ implementation controls, and enforce release gates.
 - [ ] Zero open critical findings; highs triaged with owner/date
 - [ ] SBOM updated; dependency risk addressed or accepted
 - [ ] Secrets policy verified; no hardcoded secrets
+
+## References
+
+- @.aiwg/requirements/use-cases/UC-011-validate-plugin-security.md - Security validation use case
+- @src/plugin/registry-validator.ts - Plugin security validation implementation
+- @.aiwg/requirements/nfr-modules/security.md - Security requirements
+- @.aiwg/architecture/software-architecture-doc.md - Architecture baseline (Section 4.6 Security View)
+- @.claude/commands/security-gate.md - Security gate command
+- @.claude/commands/flow-security-review-cycle.md - Security review workflow
+- @.claude/commands/security-audit.md - Comprehensive security audit

package/agentic/code/frameworks/sdlc-complete/agents/test-engineer.md

@@ -500,3 +500,12 @@ const fixtures = {
 - Coverage percentage trends
 - False positive rate
 - Test maintenance effort
+
+## References
+
+- @.aiwg/requirements/use-cases/UC-009-generate-test-artifacts.md - Use case
+- @src/testing/generators/test-case-generator.ts - Test case generator implementation
+- @.aiwg/requirements/nfr-modules/performance.md - Performance requirements (NFR-TEST-01)
+- @.aiwg/architecture/software-architecture-doc.md - Architecture baseline
+- @.claude/commands/generate-tests.md - Related slash command
+- @.claude/commands/flow-test-strategy-execution.md - Test strategy workflow

package/agentic/code/frameworks/sdlc-complete/templates/governance/adr-template.md

@@ -23,3 +23,11 @@ Positive, negative, and trade-offs. Operational impacts.
 ## Alternatives Considered
 
 Other options and why not chosen.
+
+## References
+
+Wire @-mentions for traceability:
+
+- @.aiwg/requirements/use-cases/UC-XXX.md - Driving requirement
+- @.aiwg/architecture/software-architecture-doc.md - Architecture context
+- @src/path/to/implementation.ts - Implementation (when applicable)

package/agentic/code/frameworks/sdlc-complete/templates/requirements/use-case-spec-template.md

@@ -49,7 +49,11 @@ design, testing, and traceability matrices.
 14. **Open Issues and TODOs**
     - Track unresolved questions, decisions, or dependencies.
 15. **References**
-    - Link to supporting documents (vision, supplementary spec, designs).
+    - Wire @-mentions for traceability:
+      - @.aiwg/architecture/software-architecture-doc.md - Architecture context
+      - @src/path/to/implementation.ts - Implementation
+      - @test/path/to/test.ts - Test coverage
+      - @.aiwg/requirements/nfr-modules/XXX.md - Related NFRs
 
 ## Agent Notes
 

package/agentic/code/frameworks/sdlc-complete/templates/test/master-test-plan-template.md

@@ -48,9 +48,20 @@ Establish the overarching testing strategy, scope, resources, and schedule acros
 14. **Approvals**
     - Capture sign-off requirements and responsible parties.
 
+## References
+
+Wire @-mentions for traceability:
+
+- @.aiwg/requirements/use-cases/ - Use cases covered
+- @.aiwg/architecture/software-architecture-doc.md - Architecture under test
+- @.aiwg/requirements/nfr-modules/performance.md - Performance requirements
+- @test/ - Test implementation directory
+- @src/ - Source code under test
+
 ## Agent Notes
 
 - Keep terminology aligned with the Supplementary Specification and Risk List.
 - Link to iteration-level plans and evaluation summaries for traceability.
 - Update schedule and risks after each iteration assessment.
 - Verify the Automation Outputs entry is satisfied before signaling completion.
+- **Wire @-mentions** in References section when generating this document.

package/bin/postinstall.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * AIWG Post-install Script
+ * Checks if aiwg is accessible in PATH and provides helpful guidance
+ */
+
+import { execSync } from 'child_process';
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+
+function checkPath() {
+  try {
+    // Try to run aiwg --version
+    execSync('aiwg --version', { stdio: 'ignore' });
+
+    // Success - aiwg is in PATH
+    console.log('');
+    console.log(`${GREEN}✓${RESET} aiwg installed successfully!`);
+    console.log('');
+    console.log(`  ${CYAN}aiwg demo${RESET}       Create a demo project to try it out`);
+    console.log(`  ${CYAN}aiwg doctor${RESET}     Check installation health`);
+    console.log(`  ${CYAN}aiwg -help${RESET}      Show all commands`);
+    console.log('');
+  } catch {
+    // aiwg not in PATH
+    console.log('');
+    console.log(`${YELLOW}⚠${RESET}  aiwg installed but may not be in your PATH`);
+    console.log('');
+    console.log('   If you get "command not found", add npm global bin to PATH:');
+    console.log('');
+
+    // Detect shell and provide appropriate instructions
+    const shell = process.env.SHELL || '';
+
+    if (shell.includes('zsh')) {
+      console.log(`   ${CYAN}echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc${RESET}`);
+      console.log(`   ${CYAN}source ~/.zshrc${RESET}`);
+    } else if (shell.includes('bash')) {
+      console.log(`   ${CYAN}echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc${RESET}`);
+      console.log(`   ${CYAN}source ~/.bashrc${RESET}`);
+    } else {
+      console.log(`   ${CYAN}npm config get prefix${RESET}    # Find your npm global bin directory`);
+      console.log(`   Add that path + /bin to your shell's PATH`);
+    }
+
+    console.log('');
+    console.log('   Or run directly with npx:');
+    console.log(`   ${CYAN}npx aiwg demo${RESET}`);
+    console.log('');
+  }
+}
+
+// Only run check if this is a global install
+// Local installs (devDependencies) don't need PATH
+if (!process.env.npm_config_save_dev && !process.env.npm_config_save) {
+  checkPath();
+}

package/docs/CLI_USAGE.md

@@ -3,90 +3,190 @@
 ## Installation
 
 ```bash
-npm install -g ai-writing-guide
+npm install -g aiwg
 ```
 
 ## Quick Start
 
-### Validate Files
+```bash
+# Try AIWG in under 2 minutes
+aiwg demo
+
+# Check installation health
+aiwg doctor
+
+# Deploy SDLC framework to your project
+cd your-project
+aiwg use sdlc
+```
+
+## Core Commands
+
+### demo
+
+Create a complete demo project to explore AIWG.
 
 ```bash
-# Validate single file
-aiwg validate article.md
+aiwg demo
+```
 
-# Validate multiple files
-aiwg validate docs/*.md
+Creates `~/aiwg-demo/` with:
+- Full `.aiwg/` directory structure
+- Sample intake form and requirements
+- All SDLC agents and commands deployed
+- Ready for Claude Code or Cursor
 
-# Validate with custom threshold
-aiwg validate README.md --threshold 80
+### doctor
 
-# Validate with context
-aiwg validate technical-doc.md --context technical
+Check AIWG installation health and diagnose issues.
+
+```bash
+aiwg doctor
 ```
 
-### Optimize Content
+Checks:
+- AIWG installation location
+- Version info
+- Project `.aiwg/` directory
+- Deployed agents and commands
+- Node.js version
+- MCP server availability
+- Skill Seekers (optional)
+
+### use
+
+Deploy a framework to your project.
 
 ```bash
-# Analyze and show optimization suggestions
-aiwg optimize prompt.txt
+# SDLC framework (software development)
+aiwg use sdlc
 
-# Apply optimization (creates .original backup)
-aiwg optimize prompt.txt --apply
+# Marketing framework
+aiwg use marketing
 
-# Optimize with voice guidance
-aiwg optimize article.md --voice technical --apply
+# Writing addon (voice profiles)
+aiwg use writing
+
+# All frameworks
+aiwg use all
 ```
 
-### Full Workflow (Validate → Optimize → Re-validate)
+**Options:**
+- `--provider <name>`: Target platform (claude, factory, openai, warp)
+- `--no-utils`: Skip aiwg-utils addon
+- `--force`: Overwrite existing deployments
+
+### -new
+
+Create a new project with full SDLC scaffolding.
 
 ```bash
-# Run full workflow on files
-aiwg workflow docs/*.md
+aiwg -new my-project
+cd my-project
+```
+
+### -status
 
-# Auto-apply optimizations
-aiwg workflow docs/*.md --auto-fix
+Show workspace health and installed frameworks.
 
-# Custom threshold and output
-aiwg workflow src/**/*.md --threshold 75 --format json --output report.json
+```bash
+aiwg -status
 ```
 
-### Watch Mode
+### list
+
+List installed frameworks and addons.
 
 ```bash
-# Watch markdown files with auto-fix
-aiwg watch "**/*.md" --auto-fix
+aiwg list
+```
+
+### remove
 
-# Watch with custom debounce
-aiwg watch "**/*.md" "**/*.txt" --debounce 1000
+Remove a framework or addon.
 
-# Watch without auto-fix (validation only)
-aiwg watch "docs/**/*.md"
+```bash
+aiwg remove <id>
 ```
 
-### Initialize Project
+## MCP Server
+
+### mcp serve
+
+Start the AIWG MCP server.
 
 ```bash
-# Create .aiwgrc.json config file
-aiwg init
+aiwg mcp serve
+```
 
-# Force overwrite existing config
-aiwg init --force
+### mcp install
+
+Generate MCP client configuration.
+
+```bash
+# For Claude Desktop
+aiwg mcp install claude
+
+# For Cursor IDE
+aiwg mcp install cursor
+
+# For Factory AI
+aiwg mcp install factory
+
+# Preview without writing
+aiwg mcp install claude --dry-run
 ```
 
-### Git Hooks
+### mcp info
+
+Show MCP server capabilities.
 
 ```bash
-# Install pre-commit hook
-aiwg install-hooks
+aiwg mcp info
+```
 
-# Install both pre-commit and pre-push
-aiwg install-hooks --pre-commit --pre-push
+## Channel Management
 
-# Force overwrite existing hooks
-aiwg install-hooks --force
+### --use-main
 
-# Append to existing hooks
-aiwg install-hooks --append
+Switch to bleeding edge (tracks main branch).
+
+```bash
+aiwg --use-main
+```
+
+### --use-stable
+
+Switch back to stable (npm releases).
+
+```bash
+aiwg --use-stable
+```
+
+## Maintenance
+
+### -version
+
+Show version and channel info.
+
+```bash
+aiwg -version
+```
+
+### -update
+
+Check for and apply updates.
+
+```bash
+aiwg -update
+```
+
+### -help
+
+Show all available commands.
+
+```bash
+aiwg -help
 ```
 
 ## Commands

package/docs/_config.yml

@@ -0,0 +1,5 @@
+title: AIWG - Agentic AI Workflow Guide
+description: Modular toolkit for AI-powered SDLC, marketing, and content workflows
+theme: jekyll-theme-minimal
+url: https://jmagly.github.io
+baseurl: /ai-writing-guide

package/docs/index.md

@@ -0,0 +1,106 @@
+---
+layout: default
+title: AIWG - Agentic AI Workflow Guide
+---
+
+# AIWG – Agentic AI Workflow Guide
+
+Modular toolkit for AI-powered SDLC, marketing, and content workflows.
+
+## Quick Install
+
+```bash
+npm i -g aiwg        # install globally
+aiwg demo            # try it in < 2 minutes
+```
+
+[![npm version](https://img.shields.io/npm/v/aiwg/latest?label=npm&color=CB3837&logo=npm)](https://www.npmjs.com/package/aiwg)
+[![npm downloads](https://img.shields.io/npm/dm/aiwg?color=CB3837&logo=npm)](https://www.npmjs.com/package/aiwg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/jmagly/ai-writing-guide/blob/main/LICENSE)
+
+## What is AIWG?
+
+AIWG is a modular framework toolkit that provides:
+
+- **93 Specialized AI Agents** - For SDLC, marketing, and content workflows
+- **76 Workflow Commands** - Phase transitions, reviews, deployments
+- **MCP Server** - Model Context Protocol integration
+- **Multi-Platform Support** - Claude Code, Warp Terminal, Factory AI, Cursor
+
+## Getting Started
+
+```bash
+# Install globally
+npm install -g aiwg
+
+# Create a demo project (recommended first step)
+aiwg demo
+cd ~/aiwg-demo
+
+# Or use on your existing project
+cd your-project
+aiwg use sdlc              # Deploy SDLC framework (54 agents, 48 commands)
+aiwg use marketing         # Deploy Marketing framework (37 agents, 23 commands)
+aiwg use all               # Deploy everything
+```
+
+## Features
+
+### 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
+
+### 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
+
+### Writing Quality Addon
+
+**Control your voice. Write naturally.**
+
+- 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
+
+## Platform Support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| **Claude Code** | ✅ Tested | Multi-agent orchestration |
+| **Warp Terminal** | ✅ Tested | Terminal-native workflows |
+| **Factory AI** | ✅ Tested | Native droid format |
+| **OpenAI/Codex** | 🟡 Experimental | Functional |
+| **Cursor** | 🟡 Experimental | Claude-compatible |
+
+## Documentation
+
+- [**Quick Start Guide**](https://github.com/jmagly/ai-writing-guide/blob/main/USAGE_GUIDE.md)
+- [**SDLC Framework**](https://github.com/jmagly/ai-writing-guide/tree/main/agentic/code/frameworks/sdlc-complete)
+- [**Marketing Framework**](https://github.com/jmagly/ai-writing-guide/tree/main/agentic/code/frameworks/media-marketing-kit)
+- [**Voice Framework**](https://github.com/jmagly/ai-writing-guide/tree/main/agentic/code/addons/voice-framework)
+- [**CLI Reference**](https://github.com/jmagly/ai-writing-guide/blob/main/docs/CLI_USAGE.md)
+
+## Community
+
+- **Discord**: [Join Server](https://discord.gg/BuAusFMxdA)
+- **Telegram**: [Join Group](https://t.me/+oJg9w2lE6A5lOGFh)
+- **GitHub**: [Repository](https://github.com/jmagly/ai-writing-guide)
+- **Issues**: [Report Bugs](https://github.com/jmagly/ai-writing-guide/issues)
+
+## License
+
+MIT License - Free to use, modify, and distribute.
+
+---
+
+**Full README and source code**: [github.com/jmagly/ai-writing-guide](https://github.com/jmagly/ai-writing-guide)

package/docs/quickstart.md

@@ -168,3 +168,11 @@ aiwg use writing           # Add voice profiles to SDLC project
 1. Pick your framework: [SDLC](quickstart-sdlc.md) or [MMK](quickstart-mmk.md)
 2. Pick your platform: [Claude Code](integrations/claude-code-quickstart.md), [Factory](integrations/factory-quickstart.md), or [Warp](integrations/warp-terminal-quickstart.md)
 3. Start with intake - the framework guides you from there
+
+## References
+
+- @docs/CLI_USAGE.md - Full CLI command reference
+- @agentic/code/frameworks/sdlc-complete/README.md - SDLC Framework details
+- @agentic/code/frameworks/media-marketing-kit/README.md - Marketing Framework details
+- @agentic/code/addons/voice-framework/README.md - Voice Framework addon
+- @.aiwg/architecture/software-architecture-doc.md - System architecture