A framework for agentic AI software engineering workspaces

Documentation · Template · Getting Started

---

What is Forge?

Forge gives AI agents the context they need to be genuinely useful collaborators – through layered context files, durable artifacts, and connections to real code. It works with any AI coding agent (Claude Code, Cursor, Copilot, etc.).

See FORGE.md for the complete framework documentation covering philosophy, problem statement, and detailed guidance.

"But Claude/ChatGPT/Gemini already have Projects!" – Yes, and they're useful for simple context. But they lack structure for artifacts (everything is a flat list), make evolution difficult (try refactoring a project's knowledge base), and aren't connected to your actual source code. Forge addresses all of these!

When NOT to use Forge: Skip it for quick bug fixes, small self-contained changes, throwaway prototypes, or anything with an obvious solution. If you wouldn't call a meeting about it, you probably don't need an initiative.

Golden Rules

• Start simple: Add structure only when it helps, not preemptively.
• Keep context current: Stale AGENTS.md files mislead more than they help.
• Keep, don't delete: Future-us might need that context.
• Link liberally: Connect artifacts to each other and to code.
• Refine incrementally: Messy exploration first, formal documents later.
• Know when to skip: Not every change needs a proposal.

Key Elements

Element	Purpose
AGENTS.md files	Provide layered context to AI agents
Notes	Dump raw meeting notes and transcripts
Exploration	Synthesize research into understanding
Proposal	Formalize proposals with alternatives
Decision	Record decisions and reasoning
Tickets	Define actionable work
Skills	Connect to external systems
Templates	Bootstrap new artifacts consistently

---

Getting Started

Option A: Use Copier (recommended)

Copier handles both initial setup and future updates with smart 3-way merging.

# Install Copier (requires Python 3.9+)
pip install copier

# Set up Forge in your project
copier copy gh:loehnertz/forge ./my-workspace

Option B: Use GitHub's template feature

Click the green "Use this template" button at the top of this repository to create your own Forge workspace. This gives you a fresh copy with all the framework files.

Option C: Copy files manually

If you prefer to add Forge to an existing repository without tooling:

# Clone the repository temporarily
git clone https://github.com/loehnertz/forge.git /tmp/forge

# Copy the framework files to your project
cp /tmp/forge/FORGE.md your-project/
cp -r /tmp/forge/Commands /tmp/forge/Templates your-project/

# Clean up
rm -rf /tmp/forge

1. Adapt for your AI tool

Copy Templates/AGENTS.EXAMPLE.md to the workspace root, renamed to your tool's convention, and fill in the placeholders:

Tool	Context file
Claude Code	CLAUDE.md
Cursor	.cursorrules
Windsurf	.windsurfrules
GitHub Copilot	.github/copilot-instructions.md
Aider	CONVENTIONS.md
Generic	AGENTS.md

2. Copy commands

Move files from Commands/ to your tool's command location:

Tool	Command location
Claude Code	.claude/commands/
OpenCode	.opencode/commands/

Not all tools support custom commands; check your tool's documentation.

New team member? Run /forge-onboard after copying the commands. It walks you through tool detection, configuring REPOS.md for each product, setting up your personal STYLE.md, and adding yourself to each product's TEAM.md — all in one guided session.

3. Create your first product

/forge-new-product MyProduct

Then fill in the generated AGENTS.md with product context, link related repositories, and seed References/ with existing documentation. Copy Templates/REPOS.EXAMPLE.md to the product directory as REPOS.md and fill in the local paths where you have each repository cloned (this file is gitignored — each team member has their own).

4. Start an initiative

/forge-new-initiative MyProduct My-First-Initiative

Fill in the goal and background in the initiative's AGENTS.md, then start capturing research in Exploration.md.

5. Start ideating

Work with your AI agent to explore ideas, draft proposals, and make decisions. See FORGE.md for guidance on the workflow and artifact types.

---

Updating the Framework

If you set up with Copier (Option A), pull the latest framework files with:

copier update

Copier uses git-tag-based versioning and 3-way merging, so it can intelligently merge upstream changes with your local modifications. If there are conflicts, Copier produces .rej files for manual resolution.

Make sure .copier-answers.yml is committed to your repository — Copier needs it to track the template source and version.

Always preserved (never touched by Copier):

• Your agent context file (CLAUDE.md, .cursorrules, etc.)
• Product folders and their contents
• Any other files you've added

---

Documentation

Document	Description
FORGE.md	Complete framework documentation: philosophy, workspace structure, artifact types, best practices
Templates/AGENTS.EXAMPLE.md	Template for your root context file. Adapt this for your AI tool.

---

_{MIT License}