aiwg/docs/releases/v2024.12.3-announcement.md

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

# v2024.12.3 - "It Just Works" Release

**Released**: December 14, 2025

This release focuses on **first-run experience** and **cross-platform reliability**. New users can now try AIWG in under 2 minutes with `aiwg demo`, diagnose issues with `aiwg doctor`, and install on Windows without friction.

## Highlights

| What Changed | Why You Care |
|--------------|--------------|
| `aiwg demo` command | Try the whole thing in under 2 minutes |
| `aiwg doctor` command | Diagnose installation issues instantly |
| npm discoverability + badges | Actually shows up when you search npm |
| MCP server works from any folder | No more ".aiwg not found" errors |
| PATH warning on install | Know immediately if setup needs fixing |
| Windows + cross-platform fixes | Works on Windows out of the box |
| Team directives preserved | No more lost custom rules on regenerate |
| @-mention traceability wiring | Agents navigate codebase via logical paths |
| Workspace cleanup commands | Prune stale files, archive completed plans |

## New Commands

### aiwg demo

Creates a complete demo project in `~/aiwg-demo/` with agents, commands, and sample artifacts ready to explore:

```bash
aiwg demo
cd ~/aiwg-demo
claude .
# "where are we?"
# "run security review"
```

### aiwg doctor

Health check command that diagnoses installation issues:

```bash
aiwg doctor
# Checks: PATH, installation, permissions, dependencies
# Provides: Fix suggestions for any issues found
```

### Workspace Maintenance

```bash
# Clean up .aiwg/working/ by promoting, archiving, or deleting stale files
/workspace-prune-working

# Sync documentation with codebase changes, archive completed plans
/workspace-realign
```

## Improvements

### MCP Server Auto-Discovery

The MCP server now auto-finds project root from any subdirectory by walking up the directory tree looking for `.aiwg/`. No more "project not found" errors when running from nested directories.

### Team Directives Preservation

`/aiwg-regenerate-claude` now preserves content below `<!-- TEAM DIRECTIVES -->` marker. Your custom rules, conventions, and project-specific guidance survive regeneration.

### @-Mention Traceability

Wired cross-references in 14 key files enabling agents to navigate from source code to tests to requirements to architecture documents via logical `@` paths.

## Platform Fixes

### Windows Support

- Replaced string concatenation with `path.join()` throughout
- Added Windows runner to GitHub Actions CI matrix
- All paths now work correctly on Windows

### npm Discoverability

- Added 14 discoverable keywords (aiwg, agentic-ai, mcp-server, claude-skills, etc.)
- Clear, searchable description
- Install command front and center in README

## Upgrade

```bash
# Update to latest
aiwg -update

# Or force fresh install
aiwg -reinstall

# Verify installation
aiwg doctor
```

## Resources

- [Quick Start](#quickstart)
- [CLI Reference](#ref-cli)
- [GitHub Release](https://github.com/jmagly/aiwg/releases/tag/v2024.12.3)