Framework for Orchestrated Requirements, Governance & Engineering
A structured, enterprise-grade agentic development methodology for OpenCode that adapts ceremony to complexity through progressive context engineering and constitutional governance.
FORGE is a complete AI-powered development methodology that brings structure, consistency, and quality to software projects. It combines:
- 🏗️ Progressive Context Engineering - Document chains that feed AI agents with the right context at the right time
- 📏 Multi-Track Workflows - From 30-minute hotfixes to multi-month epics, ceremony adapts to complexity
- ⚖️ Constitutional Governance - Non-negotiable principles that ensure architectural consistency
- 🔍 Adversarial Quality - AI reviews that actively look for issues before human review
- 📚 Persistent Knowledge - Decision logs, ADRs, and lessons learned that survive across sessions
FORGE is dogfooded - it was developed using itself, ensuring every feature solves real problems.
Adapt your process to task complexity:
| Track | Scope | Time | Use Case |
|---|---|---|---|
| Hotfix | 1 file, urgent | < 30 min | Production bugs |
| Quick | 1-5 tasks | < 1 day | Simple features |
| Feature | 5-20 tasks | 1-5 days | Standard features |
| Epic | 20-50 tasks | 1-4 weeks | Major features |
| Product | 50+ tasks | 4+ weeks | New products |
Nine purpose-built agents handle different phases:
- forge-pm - Product Manager: Requirements, PRDs, clarification
- forge-architect - Solution Architect: Technical design, ADRs
- forge-ux - UX Designer: User journeys, wireframes, accessibility, design specs
- forge-scrum - Scrum Master: Sprint planning, task breakdown
- forge-analyst - Business Analyst: Codebase exploration, product briefs
- forge-reviewer - Adversarial Reviewer (Claude Opus 4.6): Find real issues, not praise
- forge-reviewer-codex - Adversarial Reviewer (GPT-Codex): Independent second opinion
- forge-qa - QA Engineer: Test strategy, coverage analysis
- forge (orchestrator) - Routes to the right agent based on complexity
/forge-reviewalways invokes both reviewer agents in parallel. Their findings are synthesised — consensus issues (flagged by both models) carry the highest confidence.
Progressive context engineering through structured documents:
Constitution → Brief → PRD → Spec → Design → Architecture → Plan → Tasks → Code → Tests
↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
Principles Vision What Why UX/UI How Steps Action Build Verify
Each document:
- ✅ Self-contained (readable standalone)
- ✅ References upstream documents explicitly
- ✅ Includes metadata (version, date, status, spec ID)
- ✅ Uses explicit relative paths for implementation
Your .forge/constitution.md defines non-negotiable rules:
- Technology stack and dependency policies
- Architecture patterns and data patterns
- Quality standards and test coverage thresholds
- Security requirements and error handling
- Naming conventions and operational requirements
All decisions must comply - AI agents verify compliance automatically.
Knowledge that survives sessions:
- Decision Log - Session-level decisions auto-captured
- ADRs - Formal Architecture Decision Records
- Lessons Learned - Mistakes and insights from retrospectives
- Sprint History - Progress tracking and velocity metrics
Install FORGE in your project with one command:
# Clone FORGE
git clone https://github.com/lucaforni/forge.git
# Install in your project
npx tsx forge/install-forge.ts /path/to/your/project
# Start using FORGE
cd /path/to/your/project
opencode-
Customize your constitution:
# Edit your project principles code .forge/constitution.md -
Set project conventions:
# Define naming, git workflow, etc. code AGENTS.md -
Start building:
# In OpenCode /forge-help # See all commands /forge-specify "Feature" # Create a spec /forge-implement # Build it /forge-review # Review it
| Document | Purpose |
|---|---|
| CHEATSHEET.md | Quick reference for all commands |
| FORGE-GUIDE.md | Complete methodology guide |
| FORGE-PHILOSOPHY.md | Principles and rationale |
| INSTALL.md | Installation guide & troubleshooting |
| CONTRIBUTING.md | How to contribute to FORGE |
/forge-quick "Add email validation to signup form"
# Automatically creates tech-spec, implements, and tests
/forge-review
# Adversarial review finds issues
# Fix issues, commit, done!/forge-specify "User authentication system with OAuth"
# Creates detailed spec.md with requirements
/forge-clarify
# Refines requirements through Q&A
/forge-ux
# Designs user journeys, wireframes, accessibility spec
/forge-plan
# Creates architecture.md and plan.md
/forge-analyze
# Validates spec-plan consistency
/forge-tasks
# Breaks down into actionable tasks
/forge-implement
# Builds the feature
/forge-review
# Dual-model adversarial review across 7 dimensions (Claude Opus + GPT-Codex in parallel)
/forge-test
# Generates comprehensive tests/forge-hotfix "Fix null pointer exception in payment handler"
# Diagnoses issue, applies fix, generates tests
# No ceremony, just results
/forge-review
# Quick review before deployment/forge-brief "E-commerce platform"
# Analyzes codebase, creates product brief
/forge-prd
# Creates Product Requirements Document
/forge-architecture
# Designs system architecture with ADRs
/forge-sprint plan
# Creates sprint-001 with stories
/forge-story "User registration flow"
# Creates user story
/forge-implement
# Builds the story
/forge-sprint close
# Closes sprint, archives to history
/forge-retro
# Retrospective captures lessons learnedyour-project/
├── .opencode/ # FORGE system (installed)
│ ├── agents/ # Specialized AI agents
│ ├── commands/ # Slash commands
│ ├── skills/ # Reusable logic
│ ├── plugins/ # Event-driven automation
│ ├── tools/ # Custom tools
│ ├── templates/ # Document templates
│ └── docs/ # Methodology documentation
│
├── .forge/ # Your project data
│ ├── constitution.md # 📝 Your project principles
│ ├── specs/ # Feature specifications
│ │ └── 001-feature/
│ │ ├── spec.md # Requirements
│ │ ├── design-spec.md # UX/UI design (wireframes, components, a11y)
│ │ ├── user-journey.md # Personas & user journeys
│ │ ├── plan.md # Implementation plan
│ │ └── tasks.md # Task breakdown
│ ├── ux/
│ │ └── design-system.md # Shared design tokens & components
│ ├── knowledge/
│ │ ├── adr/ # Architecture decisions
│ │ ├── decision-log.md # Session decisions
│ │ └── lessons-learned.md # Retrospective insights
│ ├── epics/ # Epic documents
│ ├── sprints/ # Sprint tracking
│ │ ├── sprint-001.yaml # Active sprint
│ │ └── archive/ # Completed sprints
│ └── product/ # Product brief & roadmap
│
└── AGENTS.md # 📝 Your project conventions
FORGE automatically recommends the right track based on:
- Estimated task count
- Files affected
- New dependencies required
- Schema changes
- API surface changes
- Cross-module impact
- Need for new patterns
Each phase receives exactly the context it needs:
Specify Phase → Constitution, existing architecture
UX Phase → Spec, existing design system
Architecture → Constitution, PRD, design spec, existing ADRs
Implementation → Spec, design spec, plan, architecture, constitution
Review → Spec, design spec, architecture, diff, constitution
(loaded by both forge-reviewer and forge-reviewer-codex independently)
Budget-aware loading prevents context window overflow.
/forge-review runs a dual-model adversarial review — forge-reviewer
(Claude Opus 4.6) and forge-reviewer-codex (GPT-Codex) execute in parallel
and independently, then the orchestrator synthesises their findings.
Each model reviews across 7 dimensions:
- Correctness - Logic errors, edge cases, assumptions
- Security - Vulnerabilities, injection risks, data leaks
- Performance - Bottlenecks, inefficient algorithms, resource usage
- Maintainability - Complexity, documentation, extensibility
- Constitution Compliance - Adherence to project principles
- Test-Spec Coherence - Every acceptance criterion has a matching test
- UX Quality - Accessibility (WCAG 2.1 AA), usability, consistency with design spec
The synthesis report highlights consensus findings (raised by both models) as highest-confidence issues. Anti-sycophancy rules prevent generic praise.
For Epic/Product tracks:
- Multi-sprint support with automatic archiving
- Story assignment and tracking
- Velocity metrics and burndown
- Retrospectives with lessons captured
- Sprint history preserved in
sprints/archive/
❌ AI agents forget context between sessions
❌ No consistency in architectural decisions
❌ Mixing urgent fixes with long-term features
❌ Knowledge lost when agents restart
❌ AI reviews are too positive, miss real issues
✅ Progressive Context - Right information at the right time
✅ Constitutional Consistency - All decisions follow principles
✅ Adaptive Ceremony - Hotfix to Epic, ceremony matches complexity
✅ Persistent Knowledge - Decision logs, ADRs, lessons learned
✅ Adversarial Quality - AI actively finds issues before humans
We welcome contributions! See CONTRIBUTING.md for:
- How to set up development environment
- Code standards and conventions
- Testing requirements
- Pull request process
FORGE is dogfooded - all features must be developed using FORGE itself.
┌─────────────────────────────────────────────────────────────┐
│ Task Complexity Assessment │
├─────────────────────────────────────────────────────────────┤
│ │
│ < 3 tasks, 1-2 files, < 30 min → Hotfix │
│ 3-5 tasks, 2-5 files, < 1 day → Quick │
│ 5-20 tasks, 5-15 files, 1-5 days → Feature │
│ 20-50 tasks, 15-50 files, 1-4 weeks → Epic │
│ 50+ tasks, 50+ files, 4+ weeks, new system → Product │
│ │
└─────────────────────────────────────────────────────────────┘
Not sure which track? Run /forge-help and the orchestrator will assess complexity automatically.
FORGE includes custom OpenCode tools:
- trace-requirements - Trace spec requirements to implementation
- validate-spec - Check spec completeness and quality
- sprint-status - Visual sprint dashboard
Plugins provide automation:
- session-knowledge - Auto-capture decisions when sessions end
- spec-watcher - Detect spec changes and suggest updates
- pre-commit-gate - Validate compliance before commits
FORGE enforces quality through:
- Test Coverage Thresholds - Defined in constitution (typically 70%+ line, 60%+ branch)
- Review Gates - AI adversarial review before human review
- Constitution Compliance - All decisions validated against principles
- Traceability - Every line of code traces to a spec or story
"FORGE transformed how we build features. The constitutional governance ensures our microservices stay consistent, and the adversarial review catches issues we would have missed."
— Development Team Lead
"Epic workflow with sprint management is perfect for our quarterly planning. Knowledge persistence means new team members can see why decisions were made."
— Engineering Manager
- GitHub Actions integration for CI/CD
- VS Code extension for quick command access
- Spec templates for common feature types
- Analytics dashboard for velocity and quality metrics
- Multi-repo support for monorepo workflows
- Export to Jira/Linear/Asana
See FORGE-PROJECT-PLAN.md for full roadmap.
FORGE is open source software licensed under the MIT License.
- Documentation: .opencode/docs/FORGE-GUIDE.md
- Cheatsheet: CHEATSHEET.md
- Installation: INSTALL.md
- Contributing: CONTRIBUTING.md
- Issues: GitHub Issues
- Discussions: GitHub Discussions
FORGE is built on top of OpenCode, the AI-native development environment.
Special thanks to the OpenCode team for creating a platform that makes agent-driven development possible.
Built with FORGE, for FORGE
Every feature was developed using the methodology itself
Made with ❤️ by Luca Forni
Ready to forge your next project?
git clone https://github.com/lucaforni/forge.git
npx tsx forge/install-forge.ts .
opencode
/forge-help