jmagly/aiwg-regenerate-agents

Regenerate AGENTS.md

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.

Vendor-neutral: This file provides generic agent descriptions and natural language patterns suitable for any platform.

Core Principle

Team content is preserved. AIWG content is updated. Content is vendor-neutral.

Parameters

| Flag | Description | |------|-------------| | --no-backup | Skip creating backup file | | --dry-run | Preview changes without writing | | --show-preserved | List all detected preserved content and exit | | --full | Full regeneration, preserve nothing (destructive) |

Execution Steps

Step 1: Create Backup

Unless --no-backup specified:

1. Check if AGENTS.md exists
2. If exists, copy to AGENTS.md.backup-{YYYYMMDD-HHMMSS}
3. Report backup location

Step 2: Extract Preserved Content

Same preservation patterns as other platforms:

1. Explicit Preserve Blocks: <!-- PRESERVE --> ... <!-- /PRESERVE -->
2. Preserved Section Headings: Team *, Org *, Definition of Done, etc.
3. Inline Directives: Lines with directive keywords

Step 3: Analyze Project

• Languages and package managers
• Development commands
• Test framework
• CI/CD configuration
• Directory structure

Step 4: Detect AIWG State

Check installed frameworks by scanning for deployed agents/droids:

• .factory/droids/ (Factory AI)
• .opencode/agent/ (OpenCode)
• .cursor/rules/ (Cursor)
• .codex/agents/ (Codex)

Read registry for framework versions.

Step 5: Generate AGENTS.md

Document Structure:

# AGENTS.md

Project configuration for AI assistance platforms.

## Project Overview

{Description from README.md or package.json}

## Tech Stack

- **Language**: {detected languages}
- **Runtime**: {Node.js, Python, etc.}
- **Framework**: {detected frameworks}
- **Test Framework**: {detected test framework}
- **Package Manager**: {npm/yarn/pip/etc.}

## Development Commands

| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run build` | Build TypeScript to dist/ |
| `npm test` | Run Vitest test suite |
| `npm run lint` | Run ESLint |

## Project Structure

src/ → Source code test/ → Test files tools/ → CLI tools and scripts docs/ → Documentation .github/ → CI/CD workflows

---

## Team Directives

<!-- PRESERVED SECTION -->

{ALL PRESERVED CONTENT}

<!-- /PRESERVED SECTION -->

---

## AIWG Framework

This project uses the AIWG SDLC framework for software development workflows.

### Available 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 & Security:**
- `code-reviewer` - Code quality and security review
- `security-architect` - Security design and threat modeling
- `qa-engineer` - Quality assurance and testing
- `performance-engineer` - Performance optimization

**Operations & Release:**
- `devops-engineer` - CI/CD and deployment automation
- `sre` - Site reliability and monitoring
- `release-manager` - Release coordination and rollout

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

**Specialized:**
- `technical-writer` - Documentation and content
- `ux-designer` - User experience and interface design
- `data-engineer` - Data pipelines and analytics

**Deployment:** Agents are deployed to platform-specific directories:
- Claude Code: `.claude/agents/`
- GitHub Copilot: `.github/agents/`
- Factory AI: `.factory/droids/`
- Cursor: `.cursor/rules/`

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

### Workflow Commands

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

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

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

**Development:**
- `flow-guided-implementation` - Step-by-step implementation
- `generate-tests` - Generate test suite
- `setup-tdd` - Set up test-driven development
- `pr-review` - Pull request review

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

### Natural Language Requests

Use natural language to request workflows:

| Request | Maps To |
|---------|---------|
| "transition to elaboration" | flow-inception-to-elaboration |
| "run security review" | flow-security-review-cycle |
| "check project status" | project-status |
| "start iteration N" | flow-iteration-dual-track |
| "generate tests for module" | generate-tests + test-engineer |
| "review this PR" | pr-review + code-reviewer |
| "design authentication API" | api-designer |
| "optimize database queries" | database-architect + performance-engineer |

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

## Project Artifacts

{If .aiwg/ exists:}

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

## 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 Workflows: @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/commands/
- All Agents: @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/agents/
- Orchestration: @~/.local/share/ai-writing-guide/agentic/code/frameworks/sdlc-complete/docs/orchestrator-architecture.md

**Core References:**
- Orchestrator: @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/core/orchestrator.md
- Agent Design: @~/.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

**Platform-specific configurations:**
- Claude Code: CLAUDE.md
- GitHub Copilot: .github/copilot-instructions.md
- Cursor: .cursorrules
- Windsurf: .windsurfrules
- Warp: WARP.md

---

<!--
  Add team-specific notes below.
  Content in preserved sections survives regeneration.
-->

Step 6: Write Output

If --dry-run: Display content, do not write.

Otherwise:

1. Write to AGENTS.md
2. Report summary

AGENTS.md Regenerated
=====================

Backup: AGENTS.md.backup-20260113-153512

Team Content Preserved:
  ✓ Team Directives (2 sections, 21 lines)

AIWG Content Updated:
  ✓ Project commands and structure
  ✓ Agent descriptions (20 agents)
  ✓ Workflow patterns (natural language)
  ✓ Full references included

Vendor-Neutral Content:
  ✓ Generic agent descriptions
  ✓ Natural language patterns
  ✓ No platform-specific syntax
  ✓ Context size optimized: 287 lines

Output: AGENTS.md (287 lines)

Vendor-Neutral Content Rules

INCLUDE (generic descriptions):

• Agent purposes and capabilities
• Natural language workflow patterns
• Project structure and commands
• Framework references

EXCLUDE (platform-specific):

• Claude Code slash command syntax
• Copilot @-mention examples
• Cursor rule patterns
• Platform-specific invocation methods

REFERENCE (link to all):

• Full workflow catalog
• Full agent catalog
• Platform-specific context files
• Framework documentation

Target size: 250-350 lines (excluding team content)

Multi-Platform Support

AGENTS.md serves as a fallback for platforms without dedicated context files:

| Platform | Primary Context | Fallback | |----------|----------------|----------| | Claude Code | CLAUDE.md | AGENTS.md | | GitHub Copilot | .github/copilot-instructions.md | AGENTS.md | | Cursor | .cursorrules | AGENTS.md | | Windsurf | .windsurfrules | AGENTS.md | | Warp | WARP.md | AGENTS.md | | Factory AI | .factory/README.md | AGENTS.md | | OpenCode | .opencode/README.md | AGENTS.md | | Codex | ~/.codex/config | AGENTS.md |

Examples

# Regenerate AGENTS.md
/aiwg-regenerate-agents

# Preview changes
/aiwg-regenerate-agents --dry-run

# Check preserved content
/aiwg-regenerate-agents --show-preserved

# Full regeneration
/aiwg-regenerate-agents --full

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