aiwg 2026.3.2 → 2026.3.3

package/CLAUDE.md

@@ -1,5 +1,8 @@
 # AIWG
 
+
+@AIWG.md
+
 Framework for improving AI-generated content quality with voice profiles, validation tools, and specialized agents.
 
 ## Quick Start

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-agents.md

@@ -1,12 +1,16 @@
 ---
 name: aiwg-regenerate-agents
 description: Regenerate AGENTS.md with vendor-neutral content for multi-platform support
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--provider windsurf|factory] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate AGENTS.md
 
-Regenerate the AGENTS.md file, analyzing current project state while preserving team directives and organizational requirements.
+Regenerate the AGENTS.md file, analyzing current project state while preserving team directives and organizational requirements. Supports Windsurf and Factory AI (both use AGENTS.md as context file).
+
+**Hook file approach (default):** Generates `AIWG-windsurf.md` or `AIWG-factory.md` (per `--provider`) and adds directive to AGENTS.md. @-link support unverified — defaults to section-style until confirmed (see #444).
+
+**Full inject (`--full-inject`):** Embeds AIWG content inline with AIWG markers.
 
 **Used by:** Factory AI, Cursor, OpenCode, Codex, and other platforms that use AGENTS.md for configuration.
 

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-claude.md

@@ -1,12 +1,16 @@
 ---
 name: aiwg-regenerate-claude
-description: Regenerate CLAUDE.md for Claude Code with vendor-specific content only
-args: "[--no-backup] [--dry-run] [--full] [--interactive] [--guidance "text"]"
+description: Regenerate CLAUDE.md for Claude Code with hook file architecture
+args: "[--no-backup] [--dry-run] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate CLAUDE.md
 
-Regenerate the CLAUDE.md file for Claude Code integration. This command performs an **intelligent merge** - analyzing the current project state while preserving team-written content.
+Regenerate the CLAUDE.md file for Claude Code integration. This command performs an **intelligent merge** — analyzing the current project state while preserving team-written content.
+
+**Hook file architecture (default):** Generates `AIWG.md` with all AIWG context, and adds a single `@AIWG.md` directive to CLAUDE.md. This keeps CLAUDE.md minimal and user-owned.
+
+**Full injection (`--full-inject`):** Legacy mode — injects full AIWG content directly into CLAUDE.md (useful for platforms that do not support @-link loading, or user preference).
 
 **Vendor-specific filtering:** This command includes ONLY Claude Code slash commands and agents, reducing context pollution. Other vendor content is referenced but not inlined.
 
@@ -27,6 +31,31 @@ The agent must distinguish between:
 | `--no-backup` | Skip creating backup file |
 | `--dry-run` | Preview changes without writing |
 | `--full` | Full regeneration - replaces everything (destructive) |
+| `--full-inject` | Inject AIWG content directly into CLAUDE.md (legacy/compatibility mode) |
+| `--migrate` | Migrate existing full-injection to hook file approach (runs `/migrate-hook --provider claude`) |
+
+## Hook File Architecture (Default)
+
+When running without `--full-inject`:
+
+1. **Generate `AIWG.md`** — assembles AIWG context from installed framework manifests
+2. **Update `CLAUDE.md`** — minimal: user content + `@AIWG.md` directive
+
+```markdown
+# CLAUDE.md
+
+## Repository Purpose
+[your project description]
+
+@AIWG.md
+
+## Project-Specific Notes
+[your team conventions here]
+```
+
+To revert to inline injection: `/aiwg-regenerate-claude --full-inject`
+
+To disable context temporarily: `aiwg hook-disable`
 
 ## Execution Steps
 
@@ -388,6 +417,29 @@ Display the generated content, do not write.
 2. Verify write succeeded
 3. Report summary
 
+**Hook file approach (default)**:
+```
+CLAUDE.md Regenerated
+=====================
+
+Backup: CLAUDE.md.backup-20260113-152233
+
+Hook File:
+  ✓ AIWG.md generated (312 lines)
+    - Frameworks: sdlc-complete v2.1.0, aiwg-utils v1.5.0
+    - Includes: orchestrator context, RULES-INDEX, 47 commands, 12 agents
+
+CLAUDE.md Updated:
+  ✓ Team content preserved (46 lines)
+  ✓ @AIWG.md directive added
+
+Output: CLAUDE.md (49 lines), AIWG.md (312 lines)
+
+To disable AIWG context: aiwg hook-disable
+To regenerate hook only: aiwg hook-regenerate
+```
+
+**Full inject mode (`--full-inject`)**:
 ```
 CLAUDE.md Regenerated
 =====================
@@ -404,22 +456,10 @@ AIWG Content Updated:
   ✓ Tech Stack (TypeScript, Node.js 18+)
   ✓ Development Commands (12 scripts)
   ✓ Testing (Vitest)
-  ✓ Project Artifacts (@-mentions)
-  ✓ AIWG Integration
-    - Claude Commands (20 listed, 52 total)
-    - Claude Agents (15 listed, 54 total)
-    - Full references included
-
-Vendor-Specific Filtering:
-  ✓ Only Claude Code content inlined
-  ✓ Other vendors referenced for multi-vendor setups
-  ✓ Context size optimized: 387 lines
-
-Enhancements Added:
-  ✓ Linked Security Requirements → flow-security-review-cycle
-  ✓ Linked API Guidelines → architecture docs
-
-Output: CLAUDE.md (387 lines, 16,428 bytes)
+  ✓ AIWG Integration (387 lines inline)
+
+Output: CLAUDE.md (433 lines, 18,244 bytes)
+Note: Using legacy full-inject mode. Run without --full-inject to use hook file approach.
 ```
 
 ## Content Enhancement

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-codex.md

@@ -0,0 +1,130 @@
+---
+name: aiwg-regenerate-codex
+description: Regenerate Codex context file (CODEX.md or ~/.codex/instructions.md) with AIWG framework content
+category: context-regeneration
+argument-hint: "[--no-backup] [--dry-run] [--user-level] [--migrate]"
+allowed-tools: Read, Write, Edit, Bash, Glob
+model: sonnet
+---
+
+# Regenerate Codex Context
+
+Regenerate the Codex context file (`CODEX.md` or `~/.codex/instructions.md`) for OpenAI Codex integration. Performs an **intelligent merge** — preserving team-written content while updating AIWG context.
+
+## Core Principle
+
+**Team content is preserved. AIWG content is updated. Full injection used (Codex does not support @-link directives).**
+
+## Important: No @-Link Support
+
+Codex context files do not support `@filename` style includes. AIWG content is embedded directly using injection markers:
+
+```markdown
+<!-- BEGIN AIWG -->
+[AIWG content]
+<!-- END AIWG -->
+```
+
+This is different from other providers that use the hook file approach.
+
+## Parameters
+
+| Flag | Description |
+|------|-------------|
+| `--no-backup` | Skip creating backup file |
+| `--dry-run` | Preview changes without writing |
+| `--user-level` | Update `~/.codex/instructions.md` instead of project-level `CODEX.md` |
+| `--migrate` | Extract injection to `AIWG-codex.md` and reference from CODEX.md (future-proofing) |
+
+## Context File Locations
+
+| Scope | Path | Use case |
+|-------|------|----------|
+| Project-level | `CODEX.md` | Project-specific AIWG context |
+| User-level | `~/.codex/instructions.md` | User-wide context across all projects |
+
+Default: project-level `CODEX.md`. Use `--user-level` for user-wide context.
+
+## Execution Steps
+
+### Step 1: Create Backup
+
+Unless `--no-backup` specified, create `CODEX.md.backup-{YYYYMMDD-HHMMSS}`.
+
+### Step 2: Analyze Existing Content
+
+Read `CODEX.md` if it exists and categorize:
+
+- **Team content** (PRESERVE): Project rules, conventions, business logic, above or below AIWG block
+- **AIWG content** (UPDATE): Content between `<!-- BEGIN AIWG -->` and `<!-- END AIWG -->`
+
+### Step 3: Generate AIWG Content
+
+Generate AIWG content from installed framework manifests. Same content as other providers' hook files, but embedded inline.
+
+Also write `AIWG-codex.md` as a side file for reference and for potential future migration if Codex adds @-link support.
+
+### Step 4: Inject Content
+
+**If AIWG markers found**: Replace content between markers with freshly generated content.
+
+**If no markers found**: Append AIWG block to end of file (before `<!-- TEAM DIRECTIVES -->` marker if present).
+
+```markdown
+[team content preserved above]
+
+<!-- BEGIN AIWG -->
+<!-- Managed by aiwg — regenerate with: aiwg-regenerate-codex -->
+[AIWG content]
+<!-- END AIWG -->
+
+<!-- TEAM DIRECTIVES: Add project-specific guidance below -->
+```
+
+### Step 5: Report
+
+```
+Codex Context Regenerated
+==========================
+
+Backup: CODEX.md.backup-20260322-190000
+
+AIWG content: 312 lines (injected between markers)
+Side file:    AIWG-codex.md (312 lines, written for reference)
+
+Team content preserved: 22 lines
+
+Note: Codex does not support @-link directives.
+      Content embedded directly with <!-- BEGIN/END AIWG --> markers.
+      To update: aiwg-regenerate-codex
+```
+
+## Examples
+
+```bash
+# Default (project-level CODEX.md)
+/aiwg-regenerate-codex
+
+# Update user-level instructions
+/aiwg-regenerate-codex --user-level
+
+# Preview without writing
+/aiwg-regenerate-codex --dry-run
+
+# Skip backup
+/aiwg-regenerate-codex --no-backup
+```
+
+## Related Commands
+
+| Command | Regenerates |
+|---------|-------------|
+| `/aiwg-regenerate` | Auto-detect and delegate |
+| `/hook-status` | Check hook state (shows "full inject" for Codex) |
+| `/hook-regenerate --provider codex` | Rebuild AIWG-codex.md side file |
+
+## References
+
+- #439 — AIWG.md hook file architecture
+- #444 — Multi-provider @-link support research (Codex confirmed no @-link support)
+- #446 — Regenerate command suite update

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-copilot.md

@@ -1,13 +1,17 @@
 ---
 name: aiwg-regenerate-copilot
 description: Regenerate copilot-instructions.md for GitHub Copilot with vendor-specific content only
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate copilot-instructions.md
 
 Regenerate the `.github/copilot-instructions.md` file for GitHub Copilot integration, analyzing current project state while preserving team directives and organizational requirements.
 
+**Hook file approach (default):** Generates `AIWG-copilot.md` and adds `@AIWG-copilot.md` directive to copilot-instructions.md if @-link is supported. Note: Copilot @-link support is unverified — defaults to full inject until confirmed (see #444).
+
+**Full inject (`--full-inject`):** Embeds AIWG content inline with AIWG markers.
+
 **Vendor-specific filtering:** This command includes ONLY GitHub Copilot patterns and agent references, reducing context pollution. Other vendor content is referenced but not inlined.
 
 ## Core Principle

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-cursorrules.md

@@ -1,13 +1,17 @@
 ---
 name: aiwg-regenerate-cursorrules
 description: Regenerate .cursorrules for Cursor with preserved team directives
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate .cursorrules
 
 Regenerate the `.cursorrules` file for Cursor IDE integration, analyzing current project state while preserving team directives and organizational requirements.
 
+**Hook file approach (default):** Generates `AIWG-cursor.md` and adds `@AIWG-cursor.md` directive to `.cursorrules`. Note: Cursor's @-link support in `.cursorrules` is partially confirmed — see #444.
+
+**Full inject (`--full-inject`):** Embeds AIWG content inline with AIWG markers (safe fallback).
+
 ## Parameters
 
 | Flag | Description |

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-factory.md

@@ -1,7 +1,7 @@
 ---
 name: aiwg-regenerate-factory
-description: "Alias for /aiwg-regenerate-agents - Regenerate AGENTS.md"
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+description: "Regenerate AGENTS.md for Factory AI with hook file architecture"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate AGENTS.md (Factory Alias)

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-opencode.md

@@ -0,0 +1,130 @@
+---
+name: aiwg-regenerate-opencode
+description: Regenerate OpenCode context file (.opencode/context.md) with AIWG framework content
+category: context-regeneration
+argument-hint: "[--no-backup] [--dry-run] [--full-inject] [--migrate]"
+allowed-tools: Read, Write, Edit, Bash, Glob
+model: sonnet
+---
+
+# Regenerate OpenCode Context
+
+Regenerate the `.opencode/context.md` file for OpenCode integration. Performs an **intelligent merge** — preserving team-written content while updating AIWG context.
+
+## Core Principle
+
+**Team content is preserved. AIWG content is updated. Hook file approach used when supported.**
+
+## Parameters
+
+| Flag | Description |
+|------|-------------|
+| `--no-backup` | Skip creating backup file |
+| `--dry-run` | Preview changes without writing |
+| `--full-inject` | Inject full content directly into context.md (legacy/compatibility mode) |
+| `--migrate` | Migrate existing full-injection to hook file approach |
+
+## Hook File Approach (Default)
+
+By default, this command uses the hook file architecture:
+
+1. Generate `AIWG-opencode.md` with AIWG framework content
+2. Add `@AIWG-opencode.md` directive to `.opencode/context.md`
+
+**Note**: OpenCode's support for `@file` directives is not yet confirmed. If the `@` directive is not supported, use `--full-inject` as a fallback. See #444 for status.
+
+## Execution Steps
+
+### Step 1: Create Backup
+
+Unless `--no-backup` specified, create `.opencode/context.md.backup-{YYYYMMDD-HHMMSS}`.
+
+### Step 2: Analyze Existing Content
+
+Read `.opencode/context.md` if it exists and categorize:
+
+- **Team content** (PRESERVE): Project rules, conventions, business logic
+- **AIWG content** (UPDATE): Framework integration sections
+
+### Step 3: Detect Hook File Support
+
+Check whether existing `.opencode/context.md` uses a hook file directive:
+
+```bash
+grep -q "@AIWG-opencode.md" .opencode/context.md && echo "hook approach" || echo "full inject or fresh"
+```
+
+### Step 4: Generate AIWG-opencode.md
+
+Generate the hook file content from installed framework manifests (same as `aiwg hook-regenerate --provider opencode`).
+
+**If `--full-inject`**: Skip hook file generation, embed content directly.
+
+### Step 5: Write Output
+
+**Hook approach** (default):
+1. Write `AIWG-opencode.md` with generated content
+2. Update `.opencode/context.md`: preserve team content + add `@AIWG-opencode.md` directive
+
+**Full inject** (`--full-inject`):
+1. Embed full AIWG content in `.opencode/context.md` between markers:
+   ```
+   <!-- BEGIN AIWG -->
+   [content]
+   <!-- END AIWG -->
+   ```
+
+### Step 6: Report
+
+```
+OpenCode Context Regenerated
+=============================
+
+Backup: .opencode/context.md.backup-20260322-190000
+
+Hook file:    AIWG-opencode.md (312 lines, written)
+Context file: .opencode/context.md updated
+  @AIWG-opencode.md directive added
+
+Team content preserved: 14 lines
+```
+
+## Note on OpenCode @-Link Support
+
+OpenCode's support for `@file` includes within `.opencode/context.md` is currently unverified (see #444). If you encounter issues with AIWG context not loading:
+
+```bash
+# Fall back to full injection
+/aiwg-regenerate-opencode --full-inject
+```
+
+## Examples
+
+```bash
+# Default (hook file approach)
+/aiwg-regenerate-opencode
+
+# Full injection (compatibility mode)
+/aiwg-regenerate-opencode --full-inject
+
+# Preview without writing
+/aiwg-regenerate-opencode --dry-run
+
+# Migrate from full inject to hook file
+/aiwg-regenerate-opencode --migrate
+```
+
+## Related Commands
+
+| Command | Regenerates |
+|---------|-------------|
+| `/aiwg-regenerate` | Auto-detect and delegate |
+| `/hook-status` | Check hook state |
+| `/hook-regenerate --provider opencode` | Rebuild hook file only |
+| `/migrate-hook --provider opencode` | Migrate full inject to hook |
+
+## References
+
+- #439 — AIWG.md hook file architecture
+- #444 — Multi-provider @-link support research
+- #446 — Regenerate command suite update

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-warp.md

@@ -1,13 +1,17 @@
 ---
 name: aiwg-regenerate-warp
 description: Regenerate WARP.md for Warp Terminal with preserved team directives
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate WARP.md
 
 Regenerate the WARP.md file for Warp Terminal integration, analyzing current project state while preserving team directives and organizational requirements.
 
+**Hook file approach (default):** Generates `AIWG-warp.md` and adds a section or `@AIWG-warp.md` directive to WARP.md. Note: Warp's @-link support is unverified — defaults to section-style toggle until confirmed (see #444).
+
+**Full inject (`--full-inject`):** Embeds AIWG content inline in WARP.md with AIWG markers.
+
 ## Parameters
 
 | Flag | Description |

package/agentic/code/addons/aiwg-utils/commands/aiwg-regenerate-windsurfrules.md

@@ -1,13 +1,17 @@
 ---
 name: aiwg-regenerate-windsurfrules
 description: Regenerate .windsurfrules for Windsurf with preserved team directives
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--migrate] [--interactive] [--guidance "text"]"
 ---
 
 # Regenerate .windsurfrules
 
 Regenerate the `.windsurfrules` file for Windsurf (Codeium) integration, analyzing current project state while preserving team directives and organizational requirements.
 
+**Hook file approach (default):** Generates `AIWG-windsurf.md` and adds `@AIWG-windsurf.md` directive. Note: Windsurf @-link support is unverified — defaults to full inject until confirmed (see #444).
+
+**Full inject (`--full-inject`):** Embeds AIWG content inline with AIWG markers.
+
 ## Parameters
 
 | Flag | Description |

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

@@ -1,13 +1,15 @@
 ---
 name: aiwg-regenerate
 description: Regenerate platform context file with preserved team directives
-args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--interactive] [--guidance "text"]"
+args: "[--no-backup] [--dry-run] [--show-preserved] [--full] [--full-inject] [--all] [--interactive] [--guidance "text"] [--migrate]"
 ---
 
 # Regenerate Platform Context File
 
 Analyze current project state and regenerate the platform context file (CLAUDE.md, WARP.md, or AGENTS.md) while preserving team directives and organizational requirements.
 
+By default, uses the **hook file architecture**: generates `AIWG.md` (or provider equivalent) and adds a single directive to the context file. Use `--full-inject` for the legacy inline approach.
+
 ## Parameters
 
 | Flag | Description |
@@ -16,6 +18,9 @@ Analyze current project state and regenerate the platform context file (CLAUDE.m
 | `--dry-run` | Preview changes without writing |
 | `--show-preserved` | List all detected preserved content and exit |
 | `--full` | Full regeneration, preserve nothing (destructive) |
+| `--full-inject` | Inject AIWG content directly into context file (legacy/compatibility mode) |
+| `--all` | Regenerate for ALL installed providers simultaneously |
+| `--migrate` | Migrate existing full-injection to hook file approach |
 
 ## Platform Detection
 
@@ -28,21 +33,40 @@ Detect current platform automatically by checking for existing context files:
 | 3 | `.cursorrules` exists | Cursor | `/aiwg-regenerate-cursorrules` |
 | 4 | `.windsurfrules` exists | Windsurf | `/aiwg-regenerate-windsurfrules` |
 | 5 | `.github/copilot-instructions.md` exists | GitHub Copilot | `/aiwg-regenerate-copilot` |
-| 6 | `AGENTS.md` exists | Factory/OpenCode/Codex | `/aiwg-regenerate-agents` |
-| 7 | `.factory/` exists | Factory AI | `/aiwg-regenerate-agents` |
-| 8 | `.cursor/` exists | Cursor | `/aiwg-regenerate-cursorrules` |
-| 9 | `.windsurf/` exists | Windsurf | `/aiwg-regenerate-windsurfrules` |
-| 10 | `.github/agents/` exists | GitHub Copilot | `/aiwg-regenerate-copilot` |
+| 6 | `CODEX.md` exists | Codex | `/aiwg-regenerate-codex` |
+| 7 | `.opencode/context.md` exists | OpenCode | `/aiwg-regenerate-opencode` |
+| 8 | `AGENTS.md` exists + `.factory/` | Factory AI | `/aiwg-regenerate-factory` |
+| 9 | `AGENTS.md` exists | Windsurf/generic | `/aiwg-regenerate-agents` |
+| 10 | `.factory/` exists | Factory AI | `/aiwg-regenerate-factory` |
+| 11 | `.cursor/` exists | Cursor | `/aiwg-regenerate-cursorrules` |
+| 12 | `.windsurf/` exists | Windsurf | `/aiwg-regenerate-windsurfrules` |
+| 13 | `.github/agents/` exists | GitHub Copilot | `/aiwg-regenerate-copilot` |
 
 If multiple files exist, use priority order. If ambiguous, ask user.
 
+### `--all` Mode
+
+Regenerate all detected providers simultaneously:
+
+```
+Detected providers: claude, warp, cursor
+Regenerating all...
+  ✓ CLAUDE.md → AIWG.md (312 lines)
+  ✓ WARP.md → AIWG-warp.md (298 lines)
+  ✓ .cursorrules → AIWG-cursor.md (295 lines)
+Regenerated 3 providers.
+```
+
 For explicit platform targeting, use:
-- `/aiwg-regenerate-claude` → CLAUDE.md
-- `/aiwg-regenerate-warp` → WARP.md
-- `/aiwg-regenerate-agents` → AGENTS.md
-- `/aiwg-regenerate-cursorrules` → .cursorrules
-- `/aiwg-regenerate-windsurfrules` → .windsurfrules
-- `/aiwg-regenerate-copilot` → copilot-instructions.md
+- `/aiwg-regenerate-claude` → CLAUDE.md + AIWG.md
+- `/aiwg-regenerate-warp` → WARP.md + AIWG-warp.md
+- `/aiwg-regenerate-agents` → AGENTS.md + AIWG-agents.md
+- `/aiwg-regenerate-cursorrules` → .cursorrules + AIWG-cursor.md
+- `/aiwg-regenerate-windsurfrules` → .windsurfrules + AIWG-windsurf.md
+- `/aiwg-regenerate-copilot` → copilot-instructions.md + AIWG-copilot.md
+- `/aiwg-regenerate-factory` → AGENTS.md + AIWG-factory.md
+- `/aiwg-regenerate-opencode` → .opencode/context.md + AIWG-opencode.md
+- `/aiwg-regenerate-codex` → CODEX.md (full inject, no @-link support)
 
 ## Execution Steps
 
@@ -357,6 +381,19 @@ This cannot be undone (backup will still be created).
 Continue with full regeneration? [y/N]
 ```
 
+## Interactive Mode
+
+When `--interactive` is specified, ask strategic questions before regenerating:
+
+1. Which provider to regenerate (if multiple detected)
+2. Whether to use hook file or full-inject approach
+3. Whether to preserve all detected team directives
+4. Whether to create a backup
+
+**Native UX tool preference**: For each question, use the platform's native interaction tool if available (e.g., `AskUserQuestion` in Claude Code). This provides a proper input UI rather than plain text output. If no native tool is available, fall back to formatted markdown with clear options. Ask one question per interaction turn.
+
+See `@agentic/code/addons/aiwg-utils/rules/native-ux-tools.md` for the full pattern.
+
 ## Error Handling
 
 | Condition | Action |