---
namespace: aiwg
name: aiwg-regenerate-claude
platforms: [all]
description: Regenerate CLAUDE.md for Claude Code with hook file architecture
---

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document's *narrative* are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../rules/skill-discovery.md).
>
> **Exception**: The "Available Slash Commands (Claude Code)" template block below is *generated output* destined for end-user CLAUDE.md files, where Claude Code's slash-command syntax applies. Slash prefixes in that block are preserved intentionally.

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

**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.

## Core Principle

**Team content is preserved. AIWG content is updated. Only Claude-specific content is inlined.**

The agent must distinguish between:
- **Team content**: Project rules, conventions, requirements, decisions written by humans
- **AIWG content**: Framework integration, agent definitions, reference links generated by AIWG
- **Claude-specific**: Slash commands, Claude agents, Claude settings
- **Other vendors**: Copilot, Cursor, Warp commands (reference only)

## Parameters

| Flag | Description |
|------|-------------|
| `--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

### Step 1: Create Backup

Unless `--no-backup` specified:

1. Check if `CLAUDE.md` exists
2. If exists, copy to `CLAUDE.md.backup-{YYYYMMDD-HHMMSS}`
3. Report: `Backup created: CLAUDE.md.backup-20260113-152233`

If no existing file, skip backup and note: `No existing CLAUDE.md found, generating fresh.`

### Step 2: Analyze Existing Content

If existing CLAUDE.md present (and not `--full`):

**Read the file and intelligently categorize each section:**

**Team Content (PRESERVE):**
- Project-specific coding standards and conventions
- API guidelines and architectural decisions
- Security policies and compliance requirements
- Team workflows and processes
- Business rules and constraints
- Definition of Done criteria
- Historical context and rationale
- Any content that reflects human decisions about the project

**AIWG Content (UPDATE):**
- AIWG Integration sections
- Agent definitions and listings
- Command listings
- @-mention reference tables
- Orchestration instructions
- Framework version information
- Auto-detected project info (tech stack, commands)

**Identification Heuristics:**
- Team content often uses first-person ("we", "our team")
- Team content references specific business/domain terms
- Team content contains opinions, preferences, rationale
- AIWG content references `~/.local/share/ai-writing-guide`
- AIWG content has structured @-mention tables
- AIWG content lists agents, commands, frameworks

### Step 3: Analyze Project

**Detect Languages & Package Managers:**

Use Glob to find package files:
```
package.json → Node.js/npm
pyproject.toml / requirements.txt → Python
go.mod → Go
Cargo.toml → Rust
pom.xml / build.gradle → Java
composer.json → PHP
Gemfile → Ruby
```

**Extract Development Commands:**

From `package.json`:
```json
{
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "lint": "eslint ."
  }
}
```

From `Makefile`:
```makefile
build:
    go build ./...

test:
    go test ./...
```

**Detect Test Framework:**

| File Pattern | Framework |
|--------------|-----------|
| `jest.config.*` | Jest |
| `vitest.config.*` | Vitest |
| `pytest.ini`, `conftest.py` | Pytest |
| `*_test.go` | Go testing |
| `.rspec` | RSpec |
| `phpunit.xml` | PHPUnit |

**Detect CI/CD:**

| Path | Platform |
|------|----------|
| `.github/workflows/*.yml` | GitHub Actions |
| `.gitlab-ci.yml` | GitLab CI |
| `Jenkinsfile` | Jenkins |
| `.circleci/config.yml` | CircleCI |
| `azure-pipelines.yml` | Azure DevOps |

**Extract Project Description:**

Read first meaningful paragraph from `README.md` or `description` from `package.json`.

**Analyze Directory Structure:**

```
src/ or lib/ → Source code
test/ or tests/ or __tests__/ → Tests
docs/ → Documentation
scripts/ or tools/ → Tooling
.github/ → GitHub configuration
```

### Step 4: Detect AIWG State

**Check for installed frameworks:**

1. Read `.aiwg/frameworks/registry.json` if exists
2. Scan `.claude/agents/` for deployed agents (Claude-specific)
3. Scan `.claude/commands/` for deployed commands (Claude-specific)
4. Read `~/.local/share/ai-writing-guide/registry.json` for global state

**Identify active frameworks:**
- Count agent files matching sdlc-complete patterns
- Count command files matching sdlc-complete patterns
- Detect aiwg-utils presence
- Detect media-marketing-kit presence

**Check Claude-specific config:**

Read `.claude/settings.local.json` if exists for:
- Allowed read paths
- Allowed write paths
- Allowed bash commands

### Step 5: Generate CLAUDE.md

**Document Structure:**

```markdown
# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.

## Repository Purpose

{First paragraph from README.md or package.json description}

## Tech Stack

- **Languages**: {detected languages}
- **Runtime**: {Node.js version, Python version, etc.}
- **Package Manager**: {npm, yarn, pip, etc.}
- **Framework**: {React, FastAPI, etc. if detected}
- **Database**: {if detected from dependencies}

## Development Commands

```bash
# {grouped by purpose}
{extracted commands with descriptions}
```

## Testing

- **Framework**: {detected framework}
- **Run tests**: `{test command}`
- **Coverage**: `{coverage command if found}`
- **Location**: `{test directory}`

## Architecture

{Description based on directory structure}

### Directory Structure

```
{key directories with descriptions}
```

## Important Files

- `{file}` - {purpose}
{repeat for key files}

## Configuration

{List of config files and their purpose}

---

{INSERT ALL TEAM CONTENT HERE - EXACTLY AS FOUND}

{If team content exists, preserve it verbatim in its original location/order}

---

## Project Artifacts

{If .aiwg/ directory exists, wire up project-specific docs:}

| Category | Location |
|----------|----------|
| Requirements | @.aiwg/requirements/ |
| Architecture | @.aiwg/architecture/ |
| Planning | @.aiwg/planning/ |
| Testing | @.aiwg/testing/ |
| Security | @.aiwg/security/ |

{Only include rows for directories that exist}

{ENHANCEMENT: Add @-mentions below team sections to link with AIWG resources}
{Example: If team has "Security Requirements" section, add below it:}
{Related: @.aiwg/security/, /flow-security-review-cycle, /flow-compliance-validation}

---

## AIWG Integration

AIWG is installed at: `~/.local/share/ai-writing-guide`

### Installed Components

| Component | Type | Count |
|-----------|------|-------|
{table of installed frameworks, addons - only if any installed}

### Available Slash Commands (Claude Code)

**ONLY Claude Code slash commands are listed here. For full documentation, see references below.**

Commands are invoked with `/command-name`:

**Intake & Planning:**
- `/intake-wizard` - Generate project intake forms interactively
- `/intake-from-codebase` - Analyze codebase to generate intake
- `/project-status` - Check current project phase and status
- `/project-health-check` - Comprehensive project health assessment

**Phase Transitions:**
- `/flow-inception-to-elaboration` - Transition to Elaboration phase
- `/flow-elaboration-to-construction` - Transition to Construction phase
- `/flow-construction-to-transition` - Transition to Transition phase
- `/flow-gate-check` - Validate phase gate criteria

**Continuous Workflows:**
- `/flow-security-review-cycle` - Security validation workflow
- `/flow-test-strategy-execution` - Test execution workflow
- `/flow-risk-management-cycle` - Risk management workflow
- `/flow-retrospective-cycle` - Retrospective analysis

**Development:**
- `/flow-guided-implementation` - Step-by-step implementation guidance
- `/generate-tests` - Generate test suite for implementation
- `/setup-tdd` - Set up test-driven development workflow
- `/pr-review` - Perform comprehensive pull request review

**Regeneration & Setup:**
- `/aiwg-regenerate-claude` - Regenerate this CLAUDE.md file
- `/aiwg-setup-project` - Set up AIWG for new project
- `/aiwg-kb` - AIWG knowledge base queries

{Note: List only ~15-20 most commonly used commands}

**Full command catalog (52 commands):** @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/commands/

### Available Agents (Claude Code)

Agents are markdown files in `.claude/agents/`:

**Architecture & Design:**
- `architecture-designer` - System architecture and technical decisions
- `database-architect` - Database design and optimization
- `api-designer` - RESTful/GraphQL API design

**Development & Implementation:**
- `software-implementer` - Test-first development (TDD)
- `integrator` - Component integration and build management
- `test-engineer` - Comprehensive test suite creation
- `test-architect` - Test strategy and framework design

**Quality & Operations:**
- `code-reviewer` - Code quality and security review
- `security-architect` - Security design and threat modeling
- `devops-engineer` - CI/CD and deployment automation

**Management & Coordination:**
- `project-manager` - Project planning and tracking
- `product-owner` - Product vision and requirements
- `scrum-master` - Agile process facilitation

{Note: List only deployed agents, ~10-15 most relevant}

**Full agent catalog:** @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/agents/

### Orchestration

You are the Core Orchestrator. When users request workflows:

1. Interpret natural language requests
2. Map to appropriate flow commands or agents
3. Coordinate multi-agent workflows
4. Report progress with clear indicators

**Natural language mappings:**

| User says... | Maps to... |
|--------------|------------|
| "transition to elaboration" | /flow-inception-to-elaboration |
| "run security review" | /flow-security-review-cycle |
| "check status" | /project-status |
| "start iteration 2" | /flow-iteration-dual-track |
| "generate tests" | /generate-tests |
| "review this PR" | /pr-review |

**Full natural language guide:** @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/docs/simple-language-translations.md

---

## Full Reference

**AIWG Installation:** `~/.local/share/ai-writing-guide/`

**Framework Documentation:**
- SDLC Complete: @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/README.md
- All Commands (52): @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/commands/
- All Agents (54): @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/agents/
- Orchestration Guide: @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/docs/orchestrator-architecture.md

**Core References:**
- Orchestrator Prompt: @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/core/orchestrator.md
- Agent Design Rules: @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/agents/design-rules.md
- Error Recovery: @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/reliability/resilience.md

**Multi-vendor setup?**
- GitHub Copilot: .github/copilot-instructions.md
- Cursor: .cursorrules
- Windsurf: .windsurfrules
- Warp: WARP.md
- Other platforms: AGENTS.md

---

<!-- TEAM DIRECTIVES: Add project-specific guidance below this line -->
```

### Step 6: Write Output

**If `--dry-run`:**
Display the generated content, do not write.

**Otherwise:**
1. Write generated content to `CLAUDE.md`
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
=====================

Backup: CLAUDE.md.backup-20260113-152233

Team Content Preserved:
  ✓ Team Conventions (18 lines)
  ✓ Definition of Done (9 lines)
  ✓ Security Requirements (7 lines)
  ✓ API Guidelines (12 lines)

AIWG Content Updated:
  ✓ Tech Stack (TypeScript, Node.js 18+)
  ✓ Development Commands (12 scripts)
  ✓ Testing (Vitest)
  ✓ 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

When preserving team content, the agent MAY add helpful @-mentions and links below team sections **without modifying the team's words**.

**Example:**

Team wrote:
```markdown
## Security Requirements

- Must comply with SOC2
- All data encrypted at rest
- Quarterly penetration testing
```

Agent enhances:
```markdown
## Security Requirements

- Must comply with SOC2
- All data encrypted at rest
- Quarterly penetration testing

Related: /flow-security-review-cycle, /flow-compliance-validation, @.aiwg/security/
```

The team's content is **untouched**. Links are added below.

## Vendor-Specific Filtering Rules

**INCLUDE (inline in CLAUDE.md):**
- Claude Code slash commands from `.claude/commands/`
- Claude-specific agent definitions from `.claude/agents/`
- Claude settings and tool configurations
- @-mention references to project files
- Natural language mappings for Claude

**EXCLUDE (reference only, don't inline):**
- Copilot YAML agent definitions
- Cursor rule syntax and patterns
- Factory droid configurations
- Windsurf-specific instructions
- Warp terminal-specific commands (unless WARP.md also present)
- Codex skill definitions

**REFERENCE (link to, don't detail):**
- Full command catalog (all 52 commands)
- Full agent catalog (all 54 agents)
- Other vendor context files
- Framework documentation

**Target size:** 300-450 lines (excluding team content)

## Updating Outdated Information

The agent MAY update genuinely outdated information:
- Version numbers that are clearly stale
- References to files that no longer exist
- Deprecated patterns with official replacements

The agent **MUST NOT** change:
- Team opinions or preferences
- Architectural decisions (even if the agent disagrees)
- Business requirements
- Process decisions

## Examples

```bash
# Regenerate CLAUDE.md with intelligent preservation and vendor filtering
/aiwg-regenerate-claude

# Preview without writing
/aiwg-regenerate-claude --dry-run

# Full regeneration (replaces everything)
/aiwg-regenerate-claude --full

# Skip backup (use carefully)
/aiwg-regenerate-claude --no-backup
```

## Error Handling

| Condition | Action |
|-----------|--------|
| No CLAUDE.md exists | Generate fresh document |
| Backup fails | Abort, report error |
| Read error | Report error, suggest --full |
| No AIWG detected | Generate project-only content, warn |
| No package files | Generate minimal structure, warn |
| Ambiguous content | Preserve it (err on side of caution) |

## Related Commands

| Command | Regenerates |
|---------|-------------|
| `/aiwg-regenerate-claude` | CLAUDE.md (Claude Code) |
| `/aiwg-regenerate-copilot` | copilot-instructions.md (GitHub Copilot) |
| `/aiwg-regenerate-cursorrules` | .cursorrules (Cursor) |
| `/aiwg-regenerate-windsurfrules` | .windsurfrules (Windsurf) |
| `/aiwg-regenerate-warp` | WARP.md (Warp Terminal) |
| `/aiwg-regenerate-factory` | .factory/README.md (Factory AI) |
| `/aiwg-regenerate-agents` | AGENTS.md (Multi-vendor) |
| `/aiwg-regenerate` | Auto-detect vendor |

## References

- Base Template: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/regenerate-base.md
- Vendor Detection: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/docs/vendor-detection.md
- @implements @.aiwg/requirements/use-cases/UC-019-regenerate-vendor-specific.md