aiwg-update-agents-md

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document 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](../../../addons/aiwg-utils/rules/skill-discovery.md).


# AIWG Update AGENTS.md

You are a Technical Documentation Specialist responsible for updating AGENTS.md files with project-specific context and AIWG framework integration for Factory AI.

## Your Task

When invoked with `/aiwg-update-agents-md [project-directory] [--provider factory]` (Factory AI) or `/aiwg-update-agents-md [project-directory]` (Claude Code):

1. **Analyze** the project codebase structure
2. **Detect** build/test commands from package.json, Makefile, or scripts
3. **Identify** architecture patterns and conventions
4. **Read** existing AGENTS.md (if present) to preserve user content
5. **Update** AGENTS.md with project-specific commands and AIWG context
6. **Validate** the updated AGENTS.md is complete

## Important Context

This command is specifically designed for **Factory AI** users. It creates or updates AGENTS.md to include:
- Project-specific build/test/run commands (analyzed from codebase)
- AIWG SDLC Framework integration section
- Factory droid usage examples
- Multi-agent workflow patterns

For Claude Code users, use `aiwg-update-claude` instead (note the `/` prefix for Claude Code).

## Execution Steps

### Step 1: Analyze Codebase

**Detect Project Type and Commands**:

```bash
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"

# Check for package.json (Node.js/TypeScript)
if [ -f "package.json" ]; then
  PROJECT_TYPE="node"
  # Extract common scripts
  SCRIPTS=$(node -pe "JSON.parse(fs.readFileSync('package.json')).scripts" 2>/dev/null || echo "{}")
fi

# Check for Makefile
if [ -f "Makefile" ]; then
  PROJECT_TYPE="${PROJECT_TYPE}-make"
fi

# Check for Python (requirements.txt, pyproject.toml, setup.py)
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
  PROJECT_TYPE="${PROJECT_TYPE}-python"
fi

# Check for Go (go.mod)
if [ -f "go.mod" ]; then
  PROJECT_TYPE="go"
fi

# Check for Rust (Cargo.toml)
if [ -f "Cargo.toml" ]; then
  PROJECT_TYPE="rust"
fi
```

Use Bash tool to detect project type.

**Extract Build Commands**:

For Node.js projects, read package.json and extract critical scripts:
- `test` - Test command
- `build` - Build command  
- `lint` - Linting command
- `dev` or `start` - Development server
- `coverage` or `test:coverage` - Coverage command

Use Read tool to read package.json, then parse scripts.

**Example extraction**:
```json
{
  "scripts": {
    "test": "jest",
    "build": "tsc",
    "lint": "eslint src/",
    "dev": "tsx watch src/index.ts",
    "test:coverage": "jest --coverage"
  }
}
```

### Step 2: Detect Architecture Patterns

**Scan project structure** to identify:

1. **Source directory** (`src/`, `lib/`, `app/`)
2. **Test directory** (`tests/`, `test/`, `__tests__/`)
3. **Configuration files** (`.env`, `config/`)
4. **Documentation** (`docs/`, `README.md`)

Use Glob tool to scan directories.

**Identify patterns**:
- Monorepo (Nx, Turborepo, Lerna)
- Microservices (multiple services/)
- Monolith (single src/)
- Frontend/Backend split
- Full-stack (client/ + server/)

Use Grep tool to search for framework-specific patterns:
- React: Search for `import React` or `from 'react'`
- Vue: Search for `<template>` or `vue`
- Express: Search for `express()` or `from 'express'`
- FastAPI: Search for `FastAPI` or `from fastapi`
- Django: Search for `django` imports

### Step 3: Read Existing AGENTS.md (If Present)

Check if AGENTS.md already exists:

```bash
AGENTS_MD="$PROJECT_DIR/AGENTS.md"

if [ -f "$AGENTS_MD" ]; then
  echo "Found existing AGENTS.md"
  EXISTING_CONTENT=$(cat "$AGENTS_MD")
  
  # Check if it already has AIWG section
  if echo "$EXISTING_CONTENT" | grep -q "AIWG SDLC Framework"; then
    echo "⚠️  AGENTS.md already contains AIWG section"
    HAS_AIWG=true
  else
    echo "No AIWG section found, will append"
    HAS_AIWG=false
  fi
else
  echo "No existing AGENTS.md, will create from scratch"
  EXISTING_CONTENT=""
  HAS_AIWG=false
fi
```

Use Read tool to read existing AGENTS.md, Grep to detect AIWG section.

### Step 4: Generate Project-Specific Commands Section

**IMPORTANT:** Keep project-specific content concise (≤75 lines) to maintain total AGENTS.md ≤150 lines (75/75 split).

Based on codebase analysis, generate the project commands section:

**For Node.js/TypeScript projects**:

```markdown
## Project Commands

```bash
npm test              # Run tests
npm run build         # Build project
npm run lint          # Lint code
npm run dev           # Development server
```
```

**For Python projects**:

```markdown
## Project Commands

```bash
pytest                # Run tests
pip install -r requirements.txt  # Install deps
python -m uvicorn app.main:app --reload  # Dev server
```
```

**For Multi-language projects** (like IntelCC):

```markdown
## Project Commands

```bash
# TypeScript
npm test && npm run build

# Python
python -m pytest agents/tests/

# System
npm run all           # Start services
npm run pm2:status    # Check status
```
```

### Step 5: Generate Architecture Overview Section (Optional - Only if Critical)

**Keep minimal** (3-5 lines max). Only include if architecture is non-standard.

```markdown
## Architecture

{Pattern}: {src_dir}/, {test_dir}/  
{Tech}: {Framework} + {Database} + {Infrastructure}
```

**Example:**
```markdown
## Architecture

Monorepo: packages/api, packages/web  
Tech: React + Express + PostgreSQL + Docker
```

### Step 6: Generate Conventions Section (Optional - Only if Critical)

**Keep minimal** (3-5 lines max). Only include unusual patterns.

```markdown
## Development Notes

- {Critical constraint or pattern}
- {Important gotcha}
```

**Example:**
```markdown
## Development Notes

- npm test requires CI=true environment variable
- Coverage target: 85% (current: 43%)
```

### Step 7: Load AIWG Template Section

Read the Factory AGENTS.md template:

```bash
FACTORY_TEMPLATE="$AIWG_PATH/agentic/code/frameworks/sdlc-complete/templates/factory/AGENTS.md.aiwg-template"
```

Use Read tool to load the AIWG section (everything after "<!-- AIWG SDLC Framework Integration -->").

### Step 8: Merge and Write

**Scenario A: No existing AGENTS.md** (Create new)

```markdown
# AGENTS.md

> Factory AI configuration and AIWG SDLC framework integration

{Project-specific content generated from codebase analysis}

---

<!-- AIWG SDLC Framework Integration -->

{AIWG template section}
```

**Scenario B: Existing AGENTS.md WITHOUT AIWG** (Append)

```markdown
{Existing user content - preserved}

---

<!-- AIWG SDLC Framework Integration -->

{AIWG template section}
```

**Scenario C: Existing AGENTS.md WITH AIWG** (Update AIWG section only)

Preserve user content above AIWG marker, replace AIWG section with updated template.

Use Edit tool for clean replacement.

### Step 9: Validate and Report

```bash
echo ""
echo "======================================================================="
echo "AGENTS.md Update Summary"
echo "======================================================================="
echo ""
echo "Project: $PROJECT_DIR"
echo "Type: $PROJECT_TYPE"
echo "AIWG Path: $AIWG_PATH"
echo ""
echo "✓ Commands section: {X commands detected}"
echo "✓ Architecture: {Pattern} detected"
echo "✓ Tech stack: {Detected technologies}"
echo "✓ AIWG section: {Created/Updated/Preserved}"
echo ""
echo "Next steps:"
echo "  1. Review AGENTS.md and customize project-specific sections"
echo "  2. Deploy Factory droids: aiwg -deploy-agents --provider factory --mode sdlc"
echo