aiwg 2026.1.3 → 2026.1.4

package/CLAUDE.md

@@ -157,3 +157,40 @@ npm exec markdownlint-cli2 "**/*.md"
 
 <!-- TEAM DIRECTIVES: Add project-specific guidance below this line -->
 
+## Release Documentation Requirements
+
+**CRITICAL**: Every release MUST be documented in ALL of these locations:
+
+| Location | Purpose | Format |
+|----------|---------|--------|
+| `CHANGELOG.md` | Technical changelog | Keep a Changelog format with highlights table |
+| `docs/releases/vX.X.X-announcement.md` | Release announcement | Full feature documentation with examples |
+| `package.json` | Version bump | CalVer: `YYYY.MM.PATCH` |
+| GitHub Release | Public release notes | Condensed highlights + install instructions |
+| Gitea Release | Internal release notes | Same as GitHub |
+
+### Release Checklist
+
+Before pushing a version tag:
+
+1. **Update `package.json`** - Bump version following CalVer
+2. **Update `CHANGELOG.md`** - Add new version section with:
+   - Highlights table (What changed | Why you care)
+   - Detailed Added/Changed/Fixed sections
+   - Link to previous version
+3. **Create `docs/releases/vX.X.X-announcement.md`** - Full release document with:
+   - Feature highlights
+   - Code examples
+   - Migration notes (if applicable)
+   - Links to relevant documentation
+4. **Commit and tag** - `git tag -m "vX.X.X" vX.X.X`
+5. **Push to both remotes** - `git push origin main --tags && git push github main --tags`
+6. **Update GitHub Release** - Add proper release notes via `gh release edit`
+7. **Create Gitea Release** - Via MCP tool or web UI
+
+### Version Format
+
+- **CalVer**: `YYYY.MM.PATCH` (e.g., `2026.01.3`)
+- PATCH resets each month
+- Tag format: `vYYYY.MM.PATCH` (e.g., `v2026.01.3`)
+

package/agentic/code/addons/ralph/README.md

@@ -143,11 +143,28 @@ See `docs/examples/` for detailed walkthroughs:
 
 Ralph inverts traditional AI optimization from "unpredictable success" to "predictable failure with automatic recovery."
 
+## Important: When to Use Ralph
+
+**Ralph is a power tool.** Used correctly, it delivers overnight. Used incorrectly, it burns tokens producing junk.
+
+| Situation | Use Ralph? | Instead |
+|-----------|------------|---------|
+| Greenfield with no docs | **NO** | Use AIWG intake/flows first |
+| Vague requirements | **NO** | Write use cases first |
+| Clear spec, need implementation | **YES** | - |
+| Tests failing, need fixes | **YES** | - |
+| Migration with clear rules | **YES** | - |
+
+**The key insight**: Ralph excels at HOW to build, but thrashes on WHAT to build. Define your requirements first, then let Ralph implement.
+
+See [When to Use Ralph](docs/when-to-use-ralph.md) for detailed guidance on avoiding the token-burning trap.
+
 ## Related
 
-- [Quickstart Guide](docs/quickstart.md)
-- [Best Practices](docs/best-practices.md)
-- [Troubleshooting](docs/troubleshooting.md)
+- [When to Use Ralph](docs/when-to-use-ralph.md) - **Start here** - Understanding Ralph's sweet spot
+- [Quickstart Guide](docs/quickstart.md) - Getting started
+- [Best Practices](docs/best-practices.md) - Writing effective tasks
+- [Troubleshooting](docs/troubleshooting.md) - Common issues
 
 ## Credits
 

package/agentic/code/addons/ralph/docs/quickstart.md

@@ -2,6 +2,23 @@
 
 Get started with iterative AI task execution in 5 minutes.
 
+## Before You Start: Is Ralph Right for This Task?
+
+**Ralph is a power tool.** Before invoking it, ask yourself:
+
+| Question | If NO |
+|----------|-------|
+| Is my task well-defined with clear requirements? | Document requirements first |
+| Can I write a command that verifies success? | Ralph can't help with subjective goals |
+| Do I have tests/linting to validate correctness? | Add verification first |
+| Is this implementation work, not exploration? | Use Discovery Track for research |
+
+**The token-burning trap**: Ralph excels at HOW to implement but thrashes on WHAT to build. If you don't have clear requirements, Ralph will hallucinate features, contradict itself, and burn tokens producing junk.
+
+**Safe to proceed?** Read on. **Unsure?** See [When to Use Ralph](when-to-use-ralph.md) first.
+
+---
+
 ## What is Ralph?
 
 Ralph (from the "Ralph Wiggum methodology") executes AI tasks in a loop until completion criteria are met:
@@ -183,6 +200,7 @@ Ralph stores state and reports in `.aiwg/ralph/`:
 
 ## Next Steps
 
+- Read [When to Use Ralph](when-to-use-ralph.md) to understand Ralph's sweet spot
 - Read [Best Practices](best-practices.md) for effective prompt engineering
 - See [Examples](examples/) for common patterns
 - Check [Troubleshooting](troubleshooting.md) if you get stuck

package/agentic/code/addons/ralph/docs/when-to-use-ralph.md

@@ -0,0 +1,348 @@
+# When to Use Ralph (And When Not To)
+
+Understanding Ralph's sweet spot and avoiding the token-burning trap.
+
+## The Controversy
+
+Ralph divides people. Some swear by it. Others have war stories about it running all night, burning tokens, producing junk. Both are right - Ralph is a power tool, and like any power tool, it can build or destroy depending on how you use it.
+
+**The truth**: Ralph's effectiveness is directly proportional to how well-defined your project is before you invoke it.
+
+## The Two Extremes
+
+### The Disaster Case: Greenfield + Vague Directive
+
+```bash
+# DON'T DO THIS
+/ralph "make me a baking app" --completion "app works"
+```
+
+What happens:
+
+1. AI has no context about what "baking app" means
+2. No architecture decisions have been made
+3. No requirements exist
+4. AI hallucinates features, changes direction, contradicts itself
+5. Each iteration builds on shaky foundations
+6. Thrashing intensifies as hallucinated components conflict
+7. Token usage explodes
+8. Result: A mess that barely runs, if at all
+
+**Why this fails**: The AI is trying to answer "WHAT to build" while simultaneously trying to figure out "HOW to build it." These are fundamentally different problems. Mixing them creates chaos.
+
+### The Success Case: Documented Project + Implementation Focus
+
+```bash
+# DO THIS
+/ralph "Implement UC-AUTH-001 user login per the architecture doc" \
+  --completion "npm test -- auth passes AND npx tsc --noEmit passes"
+```
+
+What happens:
+
+1. UC-AUTH-001 defines exactly what login should do
+2. Architecture doc specifies technology choices
+3. AI knows the patterns, conventions, dependencies
+4. Each iteration focuses purely on implementation details
+5. Failures are specific: wrong import, missing mock, edge case
+6. AI learns from specific failures and fixes them
+7. Convergence to working code is predictable
+
+**Why this works**: The "WHAT" is settled. Ralph focuses entirely on "HOW" - the implementation mechanics where iteration genuinely helps.
+
+## The AIWG + Ralph Synergy
+
+AIWG was designed with Ralph in mind. The entire SDLC framework exists to create a corpus so complete that an AI can't thrash on what to build - it can only focus on how.
+
+### What AIWG Provides
+
+| AIWG Artifact | Eliminates This Uncertainty |
+|---------------|----------------------------|
+| Project Intake | What problem are we solving? |
+| Requirements (UC-*, US-*) | What features do we need? |
+| Software Architecture Doc | What tech stack, patterns, structure? |
+| ADRs | What decisions were made, and why? |
+| NFR modules | What are the quality requirements? |
+| Pseudo-code / interface specs | What's the API shape? |
+
+### The Transformation
+
+```
+Without AIWG:
+┌─────────────────────────────────────────────────────────┐
+│  Ralph → "What to build?" → Hallucinate → Thrash → $$$  │
+└─────────────────────────────────────────────────────────┘
+
+With AIWG:
+┌─────────────────────────────────────────────────────────┐
+│  AIWG → Defines "What" → Ralph → "How to build" → Done  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Documentation as Specification
+
+By the time you've completed AIWG's Discovery Track:
+
+- Every feature is defined in a use case
+- Every decision is recorded in an ADR
+- The architecture is documented with component diagrams
+- Non-functional requirements are explicit
+- Even pseudo-code or interface shapes may exist
+
+**The docs are one step away from code.** Ralph's job becomes mechanical: translate this specification into working code, iterate on the implementation details until tests pass.
+
+## When Ralph Excels
+
+### Implementation of Well-Defined Features
+
+```bash
+/ralph "Implement @.aiwg/requirements/UC-PAY-003.md" \
+  --completion "npm test -- payment passes"
+```
+
+The use case document tells Ralph exactly what to build. Ralph figures out the implementation.
+
+### Mechanical Transformations
+
+```bash
+/ralph "Convert src/utils/*.js to TypeScript per @.aiwg/architecture/adr-012-typescript.md" \
+  --completion "npx tsc --noEmit passes"
+```
+
+The ADR defines the transformation rules. Ralph applies them iteratively.
+
+### Test-Driven Fixes
+
+```bash
+/ralph "Fix all failing tests in src/auth/" \
+  --completion "npm test -- auth passes"
+```
+
+Tests define expected behavior. Ralph makes code match expectations.
+
+### Dependency Resolution
+
+```bash
+/ralph "Update to React 19 and fix all breaking changes" \
+  --completion "npm test passes AND npm run build succeeds"
+```
+
+Ralph excels at the tedious iteration of finding compatible versions and fixing API changes.
+
+### Code Quality Gates
+
+```bash
+/ralph "Achieve 80% test coverage in src/services/" \
+  --completion "coverage report shows src/services >80%"
+```
+
+Clear metric, well-defined scope. Ralph adds tests until the threshold is met.
+
+## When NOT to Use Ralph
+
+### Greenfield Without Documentation
+
+If you have no architecture doc, no requirements, no design - **stop**. Don't invoke Ralph. Use the AIWG intake process first.
+
+```bash
+# First: Define what you're building
+/intake-wizard
+/flow-concept-to-inception
+/flow-inception-to-elaboration
+
+# Then: Build it
+/ralph "Implement UC-001" --completion "tests pass"
+```
+
+### Vague or Subjective Goals
+
+```bash
+# BAD - cannot verify, no clear target
+/ralph "make the code better" --completion "code is good"
+/ralph "improve UX" --completion "users are happy"
+/ralph "optimize performance" --completion "app is fast"
+```
+
+If you can't write a command that verifies success, Ralph can't iterate toward it.
+
+### Research or Exploration
+
+```bash
+# BAD - this isn't an implementation task
+/ralph "figure out how authentication should work" --completion "auth design is done"
+```
+
+Use `/flow-discovery-track` or manual exploration for research. Ralph is for implementation.
+
+### Undefined Scope
+
+```bash
+# BAD - how many features is "complete"?
+/ralph "finish the app" --completion "app is complete"
+```
+
+Break this into specific, documented features first.
+
+## Ralph for Documentation (Carefully Scoped)
+
+Ralph can help with documentation itself - but only with specific, verifiable scope:
+
+```bash
+# GOOD - specific, verifiable
+/ralph "Generate ADRs for all undocumented technical decisions in src/" \
+  --completion ".aiwg/architecture/adr-*.md exists for each major pattern"
+
+# GOOD - specific output
+/ralph "Create use cases from the feature list in product-brief.md" \
+  --completion "Each feature in product-brief.md has a corresponding .aiwg/requirements/UC-*.md"
+```
+
+```bash
+# BAD - too vague
+/ralph "document the project" --completion "docs are complete"
+```
+
+## Warning Signs: Is Ralph Thrashing?
+
+Watch for these indicators:
+
+| Sign | What It Means |
+|------|---------------|
+| Same error repeating | Structural problem, not implementation detail |
+| Contradictory changes | No clear requirements to guide decisions |
+| Growing file count | Hallucinating features not in scope |
+| Unrelated files changing | Lost context, working on wrong problem |
+| "Refactoring" without tests | No verification, just churning |
+
+**If you see these**: Abort Ralph, create documentation, then resume.
+
+```bash
+/ralph-abort
+# Create/update requirements docs
+# Define architecture decisions
+/ralph "Implement [specific, documented feature]" --completion "tests pass"
+```
+
+## The Ralph Readiness Checklist
+
+Before invoking Ralph, ask:
+
+- [ ] Is the feature documented in a use case or user story?
+- [ ] Is the architecture defined (or simple enough to be implicit)?
+- [ ] Can I write a command that verifies success?
+- [ ] Is the scope specific enough to complete in <20 iterations?
+- [ ] Are tests available to validate correctness?
+
+**If any answer is "no"**: Document first, Ralph second.
+
+## Summary
+
+| Situation | Action |
+|-----------|--------|
+| Greenfield, no docs | Use AIWG intake/flows first |
+| Vague requirements | Write use cases first |
+| No architecture | Create SAD/ADRs first |
+| Clear spec, need implementation | **Use Ralph** |
+| Tests failing, need fixes | **Use Ralph** |
+| Migration with clear rules | **Use Ralph** |
+| Coverage gap with clear target | **Use Ralph** |
+
+**The formula**: AIWG defines WHAT. Ralph implements HOW. Together they work. Apart, Ralph thrashes.
+
+## Industry Perspectives and Research
+
+The debate around iterative AI execution isn't unique to Ralph. Here's what the broader industry has learned.
+
+### The Context Problem
+
+[Augment Code's research](https://www.augmentcode.com/learn/agentic-swarm-vs-spec-driven-coding) found that both agentic swarms and specification-driven development fail for the same reason: they assume the hard problem is coordination or planning, not context understanding.
+
+> "Context understanding trumps coordination strategy... Perfect coordination doesn't help when agents are coordinating around incomplete information. Comprehensive specifications don't help when you can't specify what you don't fully understand."
+
+**AIWG's answer**: Create comprehensive context *first* through documentation. Ralph then operates in a rich-context environment where iteration actually helps.
+
+### Loop Drift and Thrashing
+
+[Research into agent loops](https://www.fixbrokenaiapps.com/blog/ai-agents-infinite-loops) identified "Loop Drift" as a core failure mode - agents misinterpreting termination signals, generating repetitive actions, or suffering from inconsistent internal state.
+
+**Why this matters for Ralph**: Clear completion criteria with objective verification commands (exit codes, test results) prevent drift. Subjective criteria like "code is good" invite drift.
+
+### Context Window Degradation
+
+[Token cost research](https://agentsarcade.com/blog/reducing-token-costs-long-running-agent-workflows) confirms that context windows have a quality curve:
+
+> "Early in the window, Claude is sharp. As tokens accumulate, quality degrades. If you try to cram multiple features into one iteration, you're working in the degraded part of the curve."
+
+**Best practice**: Keep iterations focused on single changes. Ralph's git-based state persistence lets each iteration start with fresh context while inheriting the work from prior iterations.
+
+### The Double-Loop Alternative
+
+[Test Double's "double-loop model"](https://testdouble.com/insights/youre-holding-it-wrong-the-double-loop-model-for-agentic-coding) argues against prescriptive prompts entirely:
+
+> "If you have to be super prescriptive with the AI agent, I might as well write the damn code."
+
+Their approach: First loop for exploration (treat implementation as disposable), second loop for polish (traditional code review).
+
+**AIWG's response**: Both models can work. Double-loop suits exploratory greenfield work where you're discovering requirements. Ralph + AIWG suits implementation of known requirements. The key is recognizing which phase you're in.
+
+### Security Concerns
+
+[NVIDIA's security research](https://developer.nvidia.com/blog/how-code-execution-drives-key-risks-in-agentic-ai-systems/) warns:
+
+> "AI-generated code is inherently untrusted. Systems that execute LLM-generated code must treat that code with the same caution as user-supplied inputs."
+
+**Ralph's safeguards**: Auto-commit creates rollback points. Tests verify correctness. Iteration limits prevent runaway execution. But the warning is real - always review final output before production.
+
+### Success Stories
+
+The Ralph methodology has proven effective for:
+
+- **React v16 to v19 migration**: 14 hours autonomous, no human intervention ([source](https://sidbharath.com/blog/ralph-wiggum-claude-code/))
+- **Overnight multi-repo delivery**: "Ship 6 repos overnight. $50k contract for $297 in API costs" ([source](https://venturebeat.com/technology/how-ralph-wiggum-went-from-the-simpsons-to-the-biggest-name-in-ai-right-now))
+- **Test coverage improvement**: Iterative test addition until threshold met
+
+The common thread: objectively verifiable goals with clear completion criteria.
+
+### Expert Consensus
+
+Industry practitioners have converged on these principles:
+
+| Principle | Source |
+|-----------|--------|
+| Verification is mandatory | Anthropic research: "models tend to declare victory without proper verification" |
+| Context beats coordination | Augment Code: "context understanding as the prerequisite for everything else" |
+| Small iterations work better | Oreate AI: "context windows have a quality curve" |
+| Safety limits are non-negotiable | Multiple sources: cap iterations, monitor costs, use sandboxes |
+| Boring technologies work better | Oreate AI: stable APIs and mature toolchains outperform trendy alternatives |
+
+### Contrary Views
+
+Not everyone agrees Ralph is the answer:
+
+**The "double-loop" camp** argues iteration should be exploratory first, not implementation-focused. They embrace disposable code during discovery.
+
+**The "context-first" camp** argues that understanding existing systems matters more than any coordination strategy. They focus on codebase comprehension tools.
+
+**The "human-in-the-loop" camp** argues autonomous execution is inherently risky. They prefer checkpoints and approval gates.
+
+**AIWG's synthesis**: All three camps make valid points. AIWG addresses them by:
+1. Supporting exploration during Discovery Track (not Ralph)
+2. Building rich context through documentation before implementation
+3. Providing iteration limits, auto-commits, and clear abort paths
+
+Ralph isn't for every phase of development - it's for the implementation phase after discovery is complete.
+
+## Related
+
+- [Quickstart Guide](quickstart.md) - Getting started with Ralph
+- [Best Practices](best-practices.md) - Writing effective tasks and criteria
+- [AIWG SDLC Framework](../../frameworks/sdlc-complete/README.md) - Documentation-first development
+- [Discovery Track](../../frameworks/sdlc-complete/docs/phases/discovery-track.md) - How to document before you build
+
+## External Resources
+
+- [The Ralph Wiggum Breakdown](https://dev.to/ibrahimpima/the-ralf-wiggum-breakdown-3mko) - Original methodology explanation
+- [VentureBeat: Ralph Wiggum in AI](https://venturebeat.com/technology/how-ralph-wiggum-went-from-the-simpsons-to-the-biggest-name-in-ai-right-now) - Industry adoption
+- [Test Double: Double Loop Model](https://testdouble.com/insights/youre-holding-it-wrong-the-double-loop-model-for-agentic-coding) - Alternative approach
+- [Augment Code: Spec-Driven vs Agentic](https://www.augmentcode.com/learn/agentic-swarm-vs-spec-driven-coding) - Context-first perspective
+- [Reducing Token Costs](https://agentsarcade.com/blog/reducing-token-costs-long-running-agent-workflows) - Cost management strategies

package/docs/releases/v2026.01.3-announcement.md

@@ -0,0 +1,209 @@
+# 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/ai-writing-guide/releases/tag/v2026.01.3)
+- [npm Package](https://www.npmjs.com/package/aiwg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiwg",
-  "version": "2026.01.3",
+  "version": "2026.01.4",
   "description": "Modular agentic framework for AI-powered SDLC, marketing automation, and workflow orchestration",
   "type": "module",
   "bin": {

package/src/cli/index.mjs

@@ -283,8 +283,19 @@ async function handleUse(args) {
   const skipUtils = remainingArgs.includes('--no-utils');
   const filteredArgs = deployArgs.filter(a => a !== '--no-utils');
 
+  // Extract provider and target from remainingArgs to pass to addon deployments
+  const providerIdx = remainingArgs.findIndex(a => a === '--provider' || a === '--platform');
+  const provider = providerIdx >= 0 && remainingArgs[providerIdx + 1] ? remainingArgs[providerIdx + 1] : null;
+  const targetIdx = remainingArgs.findIndex(a => a === '--target');
+  const target = targetIdx >= 0 && remainingArgs[targetIdx + 1] ? remainingArgs[targetIdx + 1] : null;
+
   await runScript('tools/agents/deploy-agents.mjs', filteredArgs);
 
+  // Build common args for addon deployments (inherit provider and target)
+  const addonBaseArgs = ['--deploy-commands', '--deploy-skills'];
+  if (provider) addonBaseArgs.push('--provider', provider);
+  if (target) addonBaseArgs.push('--target', target);
+
   // Deploy aiwg-utils unless --no-utils
   if (!skipUtils) {
     console.log('');
@@ -293,8 +304,7 @@ async function handleUse(args) {
     const utilsSource = path.join(frameworkRoot, 'agentic/code/addons/aiwg-utils');
     await runScript('tools/agents/deploy-agents.mjs', [
       '--source', utilsSource,
-      '--deploy-commands',
-      '--deploy-skills',
+      ...addonBaseArgs,
     ]);
   }
 
@@ -306,8 +316,7 @@ async function handleUse(args) {
     const ralphSource = path.join(frameworkRoot, 'agentic/code/addons/ralph');
     await runScript('tools/agents/deploy-agents.mjs', [
       '--source', ralphSource,
-      '--deploy-commands',
-      '--deploy-skills',
+      ...addonBaseArgs,
     ]);
   }
 }

package/tools/agents/deploy-agents.mjs

@@ -388,120 +388,4 @@ function deepMerge(target, source) {
     }
     process.exit(1);
   }
-
-  // ============================================================================
-  // WINDSURF PROVIDER DEPLOYMENT
-  // ============================================================================
-  if (provider === 'windsurf') {
-    displayWindsurfWarning();
-
-    // Collect all agent files based on mode
-    const allAgentFiles = [];
-
-    // Writing agents
-    if (mode === 'general' || mode === 'writing' || mode === 'both' || mode === 'all') {
-      const writingAddonAgentsRoot = path.join(srcRoot, 'agentic', 'code', 'addons', 'writing-quality', 'agents');
-      const legacyAgentsRoot = path.join(srcRoot, 'agents');
-      const agentsRoot = fs.existsSync(writingAddonAgentsRoot) ? writingAddonAgentsRoot : legacyAgentsRoot;
-      if (fs.existsSync(agentsRoot)) {
-        allAgentFiles.push(...listMdFiles(agentsRoot));
-      }
-    }
-
-    // SDLC agents
-    if (mode === 'sdlc' || mode === 'both' || mode === 'all') {
-      const sdlcAgentsRoot = path.join(srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'agents');
-      if (fs.existsSync(sdlcAgentsRoot)) {
-        allAgentFiles.push(...listMdFiles(sdlcAgentsRoot));
-      }
-    }
-
-    // Marketing agents
-    if (mode === 'marketing' || mode === 'all') {
-      const marketingAgentsRoot = path.join(srcRoot, 'agentic', 'code', 'frameworks', 'media-marketing-kit', 'agents');
-      if (fs.existsSync(marketingAgentsRoot)) {
-        allAgentFiles.push(...listMdFiles(marketingAgentsRoot));
-      }
-    }
-
-    // Generate aggregated AGENTS.md (Windsurf reads this natively)
-    if (allAgentFiles.length > 0 && !commandsOnly && !skillsOnly) {
-      const agentsMdPath = path.join(target, 'AGENTS.md');
-      console.log(`\nGenerating AGENTS.md with ${allAgentFiles.length} agents for Windsurf...`);
-      generateWindsurfAgentsMd(allAgentFiles, agentsMdPath, deployOpts);
-    }
-
-    // Generate .windsurfrules with orchestration context
-    if (!commandsOnly && !skillsOnly) {
-      console.log('\nGenerating .windsurfrules orchestration file...');
-      generateWindsurfRules(srcRoot, target, deployOpts);
-    }
-
-    // Deploy commands as Windsurf workflows
-    if (deployCommands || commandsOnly) {
-      const workflowsDir = path.join(target, '.windsurf', 'workflows');
-      if (!dryRun) ensureDir(workflowsDir);
-
-      // Collect command files based on mode
-      const commandFiles = [];
-
-      if (mode === 'general' || mode === 'both' || mode === 'all') {
-        const generalCommandsRoot = path.join(srcRoot, 'commands');
-        if (fs.existsSync(generalCommandsRoot)) {
-          commandFiles.push(...listMdFilesRecursive(generalCommandsRoot));
-        }
-      }
-
-      if (mode === 'sdlc' || mode === 'both' || mode === 'all') {
-        const sdlcCommandsRoot = path.join(srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'commands');
-        if (fs.existsSync(sdlcCommandsRoot)) {
-          commandFiles.push(...listMdFilesRecursive(sdlcCommandsRoot));
-        }
-      }
-
-      if (mode === 'marketing' || mode === 'all') {
-        const marketingCommandsRoot = path.join(srcRoot, 'agentic', 'code', 'frameworks', 'media-marketing-kit', 'commands');
-        if (fs.existsSync(marketingCommandsRoot)) {
-          commandFiles.push(...listMdFilesRecursive(marketingCommandsRoot));
-        }
-      }
-
-      if (commandFiles.length > 0) {
-        console.log(`\nDeploying ${commandFiles.length} commands as Windsurf workflows to ${workflowsDir}...`);
-
-        for (const cmdFile of commandFiles) {
-          const content = fs.readFileSync(cmdFile, 'utf8');
-          const workflowContent = transformToWindsurfWorkflow(content);
-
-          // Check character limit (12000) - warn if exceeded
-          if (workflowContent.length > 12000) {
-            console.warn(`Warning: Workflow ${path.basename(cmdFile)} exceeds 12000 char limit (${workflowContent.length} chars)`);
-          }
-
-          const destFile = path.join(workflowsDir, path.basename(cmdFile));
-
-          if (dryRun) {
-            console.log(`[dry-run] deploy workflow: ${path.basename(cmdFile)}`);
-          } else {
-            fs.writeFileSync(destFile, workflowContent, 'utf8');
-            console.log(`deployed workflow: ${path.basename(cmdFile)}`);
-          }
-        }
-      }
-    }
-
-    // Note about skills
-    if (deploySkills || skillsOnly) {
-      console.log('\nNote: Skills are not directly supported for Windsurf. Reference skill files in prompts using @-mentions.');
-    }
-
-    console.log('\n' + '='.repeat(70));
-    console.log('Windsurf deployment complete. Generated files:');
-    console.log('  - AGENTS.md (agent catalog)');
-    console.log('  - .windsurfrules (orchestration context)');
-    if (deployCommands || commandsOnly) {
-      console.log('  - .windsurf/workflows/ (commands as workflows)');
-    }
-    console.log('='.repeat(70) + '\n');
-  }
 })();

package/tools/agents/providers/codex.mjs

@@ -5,15 +5,15 @@
  * to prompts format via external script.
  *
  * Deployment paths:
- *   - Agents: .codex/agents/
- *   - Commands: .codex/commands/ (via deploy-prompts-codex.mjs)
- *   - Skills: ~/.codex/skills/ (home directory)
+ *   - Agents: <project>/.codex/agents/ (project-local)
+ *   - Commands: ~/.codex/prompts/ (home directory, NOT project)
+ *   - Skills: ~/.codex/skills/ (home directory, NOT project)
  *
  * Special features:
  *   - Model replacement (opus/sonnet/haiku -> gpt variants)
  *   - --as-agents-md aggregation option
- *   - Delegates commands to deploy-prompts-codex.mjs
- *   - Delegates skills to deploy-skills-codex.mjs
+ *   - Delegates commands to deploy-prompts-codex.mjs (deploys to ~/.codex/prompts/)
+ *   - Delegates skills to deploy-skills-codex.mjs (deploys to ~/.codex/skills/)
  */
 
 import fs from 'fs';
@@ -38,8 +38,8 @@ export const aliases = ['openai'];
 
 export const paths = {
   agents: '.codex/agents/',
-  commands: '.codex/commands/',
-  skills: null,  // Skills go to ~/.codex/skills/
+  commands: null,  // Commands go to ~/.codex/prompts/ (home directory)
+  skills: null,    // Skills go to ~/.codex/skills/ (home directory)
   rules: null
 };
 
@@ -154,6 +154,10 @@ export function deployAgents(agentFiles, targetDir, opts) {
 
 /**
  * Deploy commands via external script
+ *
+ * NOTE: Codex prompts/commands go to ~/.codex/prompts/ (home directory)
+ * not to the project directory. We do NOT pass --target to let the
+ * script use its default home directory location.
  */
 export async function deployCommands(targetDir, srcRoot, opts) {
   const scriptPath = path.join(srcRoot, 'tools', 'commands', 'deploy-prompts-codex.mjs');
@@ -163,10 +167,11 @@ export async function deployCommands(targetDir, srcRoot, opts) {
     return;
   }
 
-  console.log('Delegating command deployment to deploy-prompts-codex.mjs...');
+  console.log('Delegating command deployment to deploy-prompts-codex.mjs (~/.codex/prompts/)...');
 
   return new Promise((resolve, reject) => {
-    const args = ['--target', targetDir, '--source', srcRoot];
+    // NOTE: Do NOT pass --target - Codex prompts belong in ~/.codex/prompts/ (home)
+    const args = ['--source', srcRoot];
     if (opts.dryRun) args.push('--dry-run');
     if (opts.force) args.push('--force');
     if (opts.mode) args.push('--mode', opts.mode);

package/tools/rules/deploy-rules-cursor.mjs

@@ -24,13 +24,13 @@
 import fs from 'fs';
 import path from 'path';
 
-const DEFAULT_TARGET = '.cursor/rules';
+const RULES_SUBDIR = '.cursor/rules';
 
 function parseArgs() {
   const args = process.argv.slice(2);
   const cfg = {
     source: null,
-    target: DEFAULT_TARGET,
+    target: null,  // Will be resolved to .cursor/rules/ in the appropriate project
     mode: 'all',
     dryRun: false,
     force: false,
@@ -40,13 +40,23 @@ function parseArgs() {
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--source' && args[i + 1]) cfg.source = path.resolve(args[++i]);
-    else if (a === '--target' && args[i + 1]) cfg.target = path.resolve(args[++i]);
+    else if (a === '--target' && args[i + 1]) {
+      // --target is the PROJECT root, not the final destination
+      // We always deploy to <project>/.cursor/rules/
+      const projectRoot = path.resolve(args[++i]);
+      cfg.target = path.join(projectRoot, RULES_SUBDIR);
+    }
     else if (a === '--mode' && args[i + 1]) cfg.mode = String(args[++i]).toLowerCase();
     else if (a === '--dry-run') cfg.dryRun = true;
     else if (a === '--force') cfg.force = true;
     else if (a === '--prefix' && args[i + 1]) cfg.prefix = args[++i];
   }
 
+  // Default to .cursor/rules/ in current working directory
+  if (!cfg.target) {
+    cfg.target = path.resolve(RULES_SUBDIR);
+  }
+
   return cfg;
 }