# v2026.01.3 - "Ralph Loop & Issue Management" Release

**Released**: January 13, 2026

This release introduces **Ralph Loop** for iterative AI task execution, **--interactive and --guidance flags** for all commands, a comprehensive **issue management system** with multi-provider support, **token security patterns**, and **vendor-specific regenerate commands** for reduced context overhead.

## Highlights

| What Changed | Why You Care |
|--------------|--------------|
| **Ralph Loop** | Iterative AI task execution - "iteration beats perfection" methodology |
| **--interactive & --guidance** | All commands now support interactive mode and custom guidance |
| Unified issue management | Create, update, list, sync issues across Gitea/GitHub/Jira/Linear or local files |
| Issue auto-sync | Commits with "Fixes #X" automatically update and close issues |
| Token security patterns | Secure token loading via env vars and files, never direct access |
| Vendor-specific regenerate | 30-40% smaller context files, only loads relevant platform commands |
| Man page support | `man aiwg` works after npm global install |

## Ralph Loop - Iterative AI Task Execution

The flagship feature of this release. Ralph Loop executes tasks iteratively until completion criteria are met. Errors become learning data within the loop rather than session-ending failures.

```bash
# Fix all failing tests iteratively
/ralph "Fix all failing tests in src/auth/" --completion "npm test passes"

# TypeScript migration with verification
/ralph "Convert src/utils/ to TypeScript" --completion "npx tsc --noEmit exits 0" --max-iterations 20

# Coverage target
/ralph "Add tests to reach 80% coverage" --completion "npm run coverage shows >80%"
```

### Ralph Commands

| Command | Purpose |
|---------|---------|
| `/ralph` | Execute iterative task loop |
| `/ralph-status` | Check status of current/previous loop |
| `/ralph-resume` | Resume interrupted loop from checkpoint |
| `/ralph-abort` | Abort loop and optionally revert changes |

### Natural Language Triggers

- "ralph this: [task]"
- "loop until: [criteria]"
- "keep trying until [condition]"
- "iterate on [task] until [done]"

### Philosophy

**"Iteration beats perfection"** - Instead of failing on first error, Ralph loops extract learnings from each failure and iterate with improved context. Loop state persists in `.aiwg/ralph/` for recovery.

## Command Enhancements

### --interactive Flag

All commands now support interactive mode for guided execution:

```bash
/intake-wizard --interactive
# Asks clarifying questions before proceeding
# Validates assumptions with user
# Gathers preferences for ambiguous choices
```

### --guidance Flag

Provide custom guidance to tailor command behavior:

```bash
/generate-tests --guidance "Focus on edge cases for authentication"
/pr-review --guidance "Prioritize security concerns over style"
/intake-start --guidance "This is a microservices refactoring project"
```

## Issue Management System

Unified issue tracking across platforms with configurable backends.

### Commands

| Command | Purpose |
|---------|---------|
| `/issue-create` | Create issues (Gitea, GitHub, Jira, Linear, local) |
| `/issue-update` | Update status, assignee, labels |
| `/issue-list` | List and filter issues |
| `/issue-sync` | Detect refs in commits ("Fixes #X") |
| `/issue-close` | Close with completion summary |
| `/issue-comment` | Add templated comments |

### Configuration

```yaml
# .aiwg/config.yaml
issue_tracking:
  provider: gitea  # or github, jira, linear, local
  url: https://git.example.com
  owner: myorg
  repo: myrepo
```

### Auto-Sync

Commits with issue references automatically update issues:

```bash
git commit -m "Add user validation

Fixes #42"
# Issue #42 automatically updated and closed
```

## Token Security Patterns

New security addon with patterns for secure credential handling:

```bash
# Environment variable (preferred)
export API_TOKEN="secret"
curl -H "Authorization: Bearer $API_TOKEN" ...

# Secure file loading
TOKEN=$(cat ~/.config/service/token)
curl -H "Authorization: token $TOKEN" ...
```

### Rules

- Never hard-code tokens
- Never pass tokens as command arguments
- Use heredoc for multi-line operations
- Enforce file permissions (mode 600)

## Vendor-Specific Regenerate

Context files are now 30-40% smaller by only including relevant platform content:

| Platform | Detects | Loads |
|----------|---------|-------|
| Claude Code | CLAUDE.md, .claude/ | Claude-specific commands |
| GitHub Copilot | copilot-instructions.md | Copilot-specific |
| Cursor | .cursor/ | Cursor-specific |
| Windsurf | WARP.md | Windsurf-specific |

Full catalogs are linked rather than inlined, reducing context overhead.

## Additional Features

### Gap Analysis

Unified gap analysis with natural language routing:

```bash
/gap-analysis "Compare current auth with OAuth 2.0 standards"
```

### Guided Implementation

Step-by-step implementation with checkpoints:

```bash
/flow-guided-implementation
# Breaks complex tasks into iterations
# Validates each step before proceeding
```

### Droid Bridge MCP

MCP integration for Claude Desktop and other MCP clients:

```bash
# Bridge between agentic framework and MCP protocol
aiwg use droid-bridge
```

### Man Page

```bash
npm install -g aiwg
man aiwg  # Now works!
```

## Bug Fixes

- Standardized terminology across SDLC framework (issue vs ticket)
- Consolidated `/ticket-*` commands to `/issue-*`
- Fixed addon directory deployment for Claude provider

## Upgrade

```bash
# Update to latest
npm install -g aiwg@2026.1.3

# Verify installation
aiwg --version

# Try Ralph Loop
/ralph "Run the test suite" --completion "npm test passes"
```

## Resources

- [Changelog](../../CHANGELOG.md)
- [Ralph Loop Documentation](../../agentic/code/addons/ralph/)
- [Issue Tracking Configuration](../../agentic/code/frameworks/sdlc-complete/config/issue-tracking-config.md)
- [GitHub Release](https://github.com/jmagly/aiwg/releases/tag/v2026.01.3)
- [npm Package](https://www.npmjs.com/package/aiwg)