jmagly/aiwg-regenerate-claude

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

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

{
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "lint": "eslint ."
  }
}

From 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:

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

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

# 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