# UPDATE_AGENTS.md

Workflow for updating `AGENTS.md` and optionally `DOCS.md` files to match actual codebase state. `CLAUDE.md` is a symlink to `AGENTS.md` and does not need separate processing. DOCS.md is optional and only processed if it exists (for API/code documentation).

## Workflow

### Step 1: Parse Arguments

Check for `--dry-run` flag:

- If present: Show planned changes without writing files
- If absent: Apply changes and create backups

### Step 2: Extract Verifiable Claims

Read `AGENTS.md` (and `DOCS.md` if present) and extract verifiable claims:

- File paths mentioned
- Directory structures described
- Commands referenced (build tools, scripts, package managers)
- Rules about what to edit/not edit
- Workflow descriptions
- Testing patterns
- Dependencies and integrations

**DOCS.md-specific claims (if file exists):**

- API endpoint paths and HTTP methods
- Function signatures and parameters
- Type definitions and interfaces
- Response schemas and examples
- Environment variables for API configuration

### Step 3: Verify and Fix Claims

Check each claim against actual codebase and auto-fix discrepancies:

**File/Directory claims:**

- Use `ls`, `fd`, or `tree` to verify paths exist
- If path changed: update to new path
- If path deleted: mark section for removal or update

**Command claims:**

- Verify commands exist in `justfile`, `package.json`, `Makefile`, or scripts
- If command syntax changed: update to match actual command
- If command removed: mark for removal

**Linting configuration:**

- Locate lint-staged config (`.lintstagedrc.js`, `.lintstagedrc.json`, `lint-staged` in `package.json`)
- Extract lint commands for each file pattern
- If linting instructions don't match: update to match config

**Code structure claims:**

- Read actual files to verify patterns described
- Update outdated patterns to match current code

**API documentation claims (DOCS.md):**

- Verify documented endpoints exist in route files
- Verify function signatures match actual code
- Verify type definitions match actual types
- If endpoint removed: mark for removal
- If signature changed: update to match actual signature

### Step 4: Discover Undocumented Patterns

Scan for patterns not mentioned in context files:

**Task runners:**

- Read `justfile` and list recipes not documented
- Read `package.json` scripts not documented
- Read `Makefile` targets not documented

**Lint configuration:**

- If lint-staged exists but no linting section in AGENTS.md, draft one

**Build/test commands:**

- Check for undocumented build, test, or deploy commands

**API patterns (for DOCS.md):**

- Scan for undocumented API routes
- Detect undocumented exported functions
- Find undocumented public types/interfaces
- If DOCS.md doesn't exist but APIs are detected, suggest creating it

### Step 5: Apply Updates

**If --dry-run:**

Show preview of all changes without writing:

```
## Planned Changes

{file}:
  - Line X: "{old}" → "{new}"
  - Section Y: [REMOVE - path no longer exists]

## Suggested Additions

{file}: Consider adding section:
[Draft section content]
```

**If NOT --dry-run:**

1. Apply all fixes to the file directly
2. Report changes made

### Step 6: Report Summary

**Format for fixes:**

```
## Fixed

✓ {file}: Updated {claim} → {new_value}
✓ {file}: Removed outdated {claim}
✓ DOCS.md: Updated endpoint /api/users → /api/v2/users
✓ DOCS.md: Fixed function signature createUser()
```

**Format for suggestions:**

```
## Suggested Additions

{file}: Consider adding:

### [Section Name]

[Draft content based on discovered patterns]

---
Note: DOCS.md not found. Consider creating it to document:
- 5 API endpoints detected in src/routes/
- 12 exported functions in src/lib/
```

**If no changes needed:**

```
✓ All context files are up to date
⊘ DOCS.md not found (optional, skipped)
```

## Notes

- Focus on factual claims, not stylistic opinions
- Preserve user's writing style when making fixes
- Only suggest additions for genuinely useful patterns
- Adapt discovery to project type (web, CLI, library, etc.)
- DOCS.md is optional—skip gracefully if not present
- Suggest DOCS.md creation only if significant APIs/public interfaces detected