# Forge Enhancement Roadmap

**Comprehensive implementation plan for transforming Forge into a fully automated, orchestrated workflow system.**

**Plan Created**: 2026-02-10
**Status**: Phase 2 complete. PRs 0-6 merged, PR7-PR8 pending.
**Timeline**: Originally 3-4 weeks; Phases 0-2 complete as of March 2026.
**Strategy**: Quick wins first → Build testing foundation → Add automation → Enable extensibility

---

## Table of Contents

1. [Overview](#overview)
2. [Implementation Strategy](#implementation-strategy)
3. [PR Sequence & Dependencies](#pr-sequence--dependencies)
4. [Detailed PR Breakdown](#detailed-pr-breakdown)
5. [Success Metrics](#success-metrics)
6. [Tracking & Management](#tracking--management)

---

## Overview

Transform Forge from a documentation-driven workflow into a fully automated, orchestrated workflow system with:

- ✅ **Enhanced Multi-Agent Support**: Universal AGENTS.md + 8 supported agents (Claude Code, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)
- ✅ **Comprehensive Testing**: 80%+ code coverage, E2E tests, mutation testing
- ✅ **Advanced Security**: CODEOWNERS, commit signing, extended OWASP checks
- ✅ **CLI Automation**: Automated `/research`, `/plan`, `/ship`, `/review` commands
- ✅ **Plugin Architecture**: Extensible system for custom checks and workflows
- ✅ **Quality Dashboards**: Metrics, auto-merge, release automation

---

## Implementation Strategy

**Philosophy**: Deliver immediate value while building towards comprehensive improvements.

```
Quick Wins (Week 1) → Testing Foundation (Week 2) → Automation (Week 2-3) → Extensibility (Week 3-4)
```

### Phased Approach

**Phase 0: Architecture Simplification (PREREQUISITE)**
- Simplify from 11 agents to 5 Tier 1 + 3 Tier 2
- Universal AGENTS.md + optional agent-specific configs
- Zero coordination complexity
- **Timeline**: 2-3 days

**Phase 1: Foundation & Quick Wins (Week 1)**
- PR1: Critical fixes (Greptile, /validate, Windows compatibility)
- PR2: Security enhancements (CODEOWNERS, signing, semantic commits)
- PR3: Testing infrastructure (coverage, E2E, snapshots)

**Phase 2: Workflow Automation (Week 2)**
- PR4: CLI automation (command dispatcher, automated stages)
- PR5: Advanced testing (mutation testing, benchmarks, security expansion)

**Phase 3: Extensibility & Polish (Week 3-4)**
- PR6: Plugin architecture (config system, custom checks)
- PR7: Documentation automation (validators, consistency checking)
- PR8: Advanced features (metrics dashboard, auto-merge, SBOM)

---

## PR Sequence & Dependencies

```
PR0 (Simplification) → PR1 (Fixes) → PR2 (Security) → PR3 (Test Infra)
                                            ↓
                                    PR4 (Automation) → PR5 (Test Expansion)
                                            ↓
                              PR5.5 (Skills) → PR6 (Plugins) → PR7 (Docs) → PR8 (Advanced)
```

### Dependency Chain

| PR | Depends On | Blocks | Status |
|----|------------|--------|--------|
| PR0 | None | PR1 | ✅ MERGED (2026-02-12, PR #26) |
| PR1 | PR0 | PR2 | ✅ MERGED (2026-02-13, PR #28) |
| PR2 | PR1 | PR3 | ✅ MERGED (2026-02-14, PR #29) |
| PR3 | PR2 | PR4 | ✅ MERGED (2026-02-14, PR #30) |
| PR4 | PR3 | PR5 | ✅ MERGED (2026-02-19, PR #33) |
| PR5 | PR4 | PR5.5 | ✅ MERGED (2026-02-20, PR #40) |
| PR5.5 | PR5 | PR6 | ✅ MERGED (2026-02-23, PR #43) |
| PR6 | PR5.5 | PR7 | ✅ MERGED (2026-02-21, PR #41) |
| PR7 | PR6 | PR8 | Planned |
| PR8 | PR7 | None | Planned |

---

## Detailed PR Breakdown

### **PR0: Architecture Simplification** 🎯
**Branch**: `feat/pr0-agent-simplification`
**Beads Issue**: `forge-wp2`
**PR**: #26
**Status**: ✅ **COMPLETED & MERGED** (2026-02-12)
**Timeline**: 2-3 days
**Type**: `refactor`
**Impact**: Critical - Foundation for all subsequent PRs

#### Key Deliverables
1. Universal AGENTS.md (works with ALL agents)
2. Agent-specific configs (Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)
3. Smart setup with auto-detection
4. Documentation: ARCHITECTURE.md, CONFIGURATION.md, MCP_SETUP.md
5. Zero coordination complexity

[See complete details in master plan]

---

### **PR1: Critical Fixes & Immediate Improvements** ⚡
**Beads Issue**: `forge-bdo`
**Status**: Blocked (waiting on PR0)
**Timeline**: 1-2 days
**Impact**: High

#### Key Deliverables
1. Unified /validate script - Orchestrate all validation steps
2. Lefthook Windows compatibility fixes
3. Package size monitoring workflow
4. Manual review guidance - Best practices for achieving high quality scores

---

### **PR2: Branch Protection & Security Enhancements** 🔒
**Beads Issue**: `forge-aom`
**Status**: Blocked (waiting on PR1)
**Timeline**: 1-2 days
**Impact**: High

#### Key Deliverables
1. CODEOWNERS file
2. Commit signing requirement
3. Additional branch protection
4. Semantic commit validation
5. SECURITY.md

---

### **PR3: Testing Infrastructure Foundation** 🧪
**Beads Issue**: `forge-5uh`
**Status**: Blocked (waiting on PR2)
**Timeline**: 2-3 days
**Impact**: High

#### Key Deliverables
1. Code coverage integration (c8, 80% thresholds)
2. E2E test framework
3. Snapshot testing
4. CI workflow enhancements

---

### **PR4: CLI Command Automation** 🤖
**Beads Issue**: `forge-9tp`
**PR**: #33
**Status**: ✅ **COMPLETED & MERGED** (2026-02-19)
**Timeline**: 3-4 days
**Impact**: High

#### Key Deliverables
1. Command dispatcher (bin/forge-cmd.js)
2. Intelligent /status with stage detection (1-9)
3. Automated /research, /plan, /ship, /review commands
4. PR body auto-generation
5. Review aggregator

---

### **PR5: Advanced Testing Expansion** 🔬
**Beads Issue**: `forge-01p`
**Research**: [docs/research/advanced-testing.md](docs/research/advanced-testing.md) (PR #36)
**Status**: Research complete, ready for `/plan`
**Timeline**: 2-3 days
**Impact**: Medium

#### Key Deliverables
1. Mutation testing (Stryker, 70%+ score)
2. Performance benchmarks
3. Extended security tests (OWASP A02, A07)
4. Test quality dashboard

---

### **PR5.5: Skills Restructure for skills.sh** 📦
**Status**: Scoped (part of PR6 research)
**Timeline**: 1-2 days
**Impact**: Medium

#### Key Deliverables
1. Restructure parallel-ai into 4 focused skills (search, extract, deep-research, enrichment)
2. Adopt `parallel-cli` as primary method (fallback to curl)
3. Add citation-standards rule
4. Update sonarcloud skill for skills.sh format
5. Publish to GitHub (auto-registers on skills.sh)

---

### **PR6: Plugin Architecture & Smart Recommendations** 🔌
**Beads Issue**: `forge-a7n`
**Research**: [docs/research/plugin-architecture.md](docs/research/plugin-architecture.md) (PR #37)
**Status**: Research complete, ready for `/plan`
**Timeline**: 4-5 days
**Impact**: High (flagship feature)

#### Key Deliverables
1. Plugin catalog — tech stack to tool mapping (JSON data structure)
2. Expanded detection — 20+ frameworks, databases, auth, payments, LSPs
3. CLI-first recommendation engine — prefer CLI tools over MCPs
4. Pricing transparency — free alternatives for every paid tool
5. Budget modes — Free/OpenSource/Startup/Professional/Custom
6. Installation orchestration — `npx skills add`, `npx add-mcp`, config generation, LSP setup
7. Absorbs forge-mlm scope (sync, validate; AI creation deferred to PR8)

---

### **PR7: Documentation Automation** 📚
**Beads Issue**: `forge-jvc`
**Status**: Blocked (waiting on PR6)
**Timeline**: 2-3 days
**Impact**: Medium

#### Key Deliverables
1. Auto-documentation updater
2. Link validator
3. Example code validator
4. Consistency checker

---

### **PR8: Advanced Features & Dashboard** 📊
**Beads Issue**: `forge-dwm`
**Status**: Blocked (waiting on PR7)
**Timeline**: 3-4 days
**Impact**: Medium

#### Key Deliverables
1. Workflow metrics dashboard
2. Auto-merge on green PRs
3. Stale PR/issue automation
4. Release notes automation
5. SBOM generation

---

## Success Metrics

### After PR1-PR3 (Week 1)
- ✅ Greptile workflow fixed with multi-tool support
- ✅ 80%+ code coverage
- ✅ E2E tests covering main workflow
- ✅ Branch protection with CODEOWNERS

### After PR4-PR5 (Week 2)
- ✅ All 9 commands executable via CLI
- ✅ Automated PR body generation
- ✅ 70%+ mutation score
- ✅ Performance benchmarks established

### After PR6-PR8 (Week 3-4)
- ✅ Plugin system with 3+ example plugins
- ✅ Automated documentation validation
- ✅ Workflow metrics dashboard
- ✅ Release automation

---

## Tracking & Management

### Beads Issues

All PRs tracked in Beads with proper dependencies:

| PR | Issue ID | Status | Priority | Blocked By |
|----|----------|--------|----------|------------|
| PR0 | forge-wp2 | ✅ Completed (PR #26) | P0 | None |
| PR1 | forge-bdo | ✅ Completed (PR #28) | P1 | None |
| PR2 | forge-aom | ✅ Completed (PR #29) | P1 | None |
| PR3 | forge-5uh | ✅ Completed (PR #30) | P1 | None |
| PR4 | forge-9tp | ✅ Completed (PR #33) | P2 | None |
| PR5 | forge-01p | ✅ Completed (PR #40) | P2 | None |
| PR5.5 | forge-qst | ✅ Completed (PR #43) | P2 | PR5 |
| PR6 | forge-a7n | ✅ Completed (PR #41) | P2 | PR5.5 |
| PR7 | forge-jvc | Ready | P3 | PR6 |
| PR8 | forge-dwm | Blocked | P3 | PR7 |
| ~~Skills CLI~~ | ~~forge-mlm~~ | ~~Absorbed into PR5.5 + PR6 + PR8~~ | — | — |

**View all issues**: `forge list`
**View ready work**: `forge ready`
**View blocked issues**: `bd blocked`

### Git Workflow

Each PR follows the Forge workflow:

```
/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
```

**Current branch**: `master` (ready for next feature branch)
**Base branch**: `master`

### Plan Files

- **Master Plan**: `docs/plans/*.md` (global, tracked by Claude Code)
- **Roadmap**: `docs/ROADMAP.md` (repository, git-tracked)
- **Beads Tracking**: `.beads/issues.jsonl` (git-tracked)

---

## Rollback Strategy

Each PR is self-contained and can be rolled back independently:

- **PR0**: Revert to current agent support model
- **PR1**: Revert workflow changes, restore original lefthook
- **PR2**: Remove CODEOWNERS, revert branch protection
- **PR3**: Remove coverage requirements, remove E2E tests
- **PR4**: Remove CLI commands, keep manual workflow
- **PR5**: Remove mutation tests, remove benchmarks
- **PR5.5**: Revert skills to monolithic format in .claude/skills/
- **PR6**: Remove plugin system, keep core functionality
- **PR7**: Remove doc automation, keep manual verification
- **PR8**: Remove advanced features, keep core workflow

---

## Next Steps

1. ✅ **PR4 Completed** — CLI command automation merged (PR #33)

2. ✅ **Research complete** for PR5 and PR6:
   - PR5 research: [docs/research/advanced-testing.md](docs/research/advanced-testing.md) (PR #36)
   - PR6 research: [docs/research/plugin-architecture.md](docs/research/plugin-architecture.md) (PR #37)
   - PR6 scope expanded: smart plugin recommendations, CLI-first, pricing transparency
   - forge-mlm absorbed into PR5.5 + PR6 + PR8

3. **Next: `/plan advanced-testing`** to start PR5 implementation

---

## Resources

- **Master Plan**: `docs/plans/*.md`
- **Beads Issues**: `forge list` or `forge show <issue-id>`
- **Workflow Guide**: [AGENTS.md](../AGENTS.md)
- **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)

---

**Last Updated**: 2026-02-20
**Current Phase**: Phase 2 complete, research done for Phase 3
**Next Milestone**: Plan and implement PR5 (Advanced Testing)