What is Open Forge?

Open Forge is a small Markdown framework for working with AI agents, built around your projects, your tools, and the way you like to work. It gives an agent a map to your rules and project knowledge, and a place to keep useful outcomes for the next task.

At its core, it's Markdown, rules, and links. Install it, ask your agent to work as usual, and add only what makes the next task easier.

Start using it

Already have AGENTS.md or CLAUDE.md? Install adds a marked Open Forge section and keeps your existing text. It also creates the selected files under .agents/. Save your current work before trying it.

For a trial, use a separate local clone and copy any additional local files you need. Installation explains the baseline and undo steps.

With Node.js 22.18 or later:

npm install -g @thelithiumforge/open-forge@beta
cd /path/to/your-project
open-forge install

For a first try, choose Essentials. Keep Root keys unless your workspace already declares another metadata form. Review the plan before applying it, then inspect the new files and changes with git status and git diff. Installation explains the other choices, other setup methods, and how to change your setup later.

Now ask your agent for a normal task. In an existing project, ask how its tests run:

Explain how this project runs its tests. Follow AGENTS.md, and name the Open Forge files you read.

In a new project, give the agent a first build request. Try the greenfield demo for a concrete example.

You don't need to choose a workflow, install Extensions, or write a specification first. The ten-minute guide takes you through adding a rule, keeping a useful fact, and finding context for the next task. The demos give you a project to try it on.

The basic flow

Your request
    |
AGENTS.md -> loader
    |
Startup rules + relevant links
    |
Work, keep useful outcomes

An agent doesn't need to know everything, but it does need to know where everything is. Each context folder has a short entrypoint, a Markdown file named _{folder-name}.md that lists what's inside. The rules load startup context, then guide the agent to the branches the task needs. Other content opens when selected, tagged to load, or explicitly required by a loaded rule.

This is Adaptive Context Engineering (ACE): start from the task, bring in context as the work unfolds, and keep what's useful next time. Loading and tags explains the exact rules.

Open Forge works with any harness, the tool that runs your agent, that reads AGENTS.md or the CLAUDE.md bridge. Keep your hooks, custom agents, and tools. A translator such as APM can help install harness-specific definitions in several tools.

Three parts, one of them required

Part	What it is	Required?
Framework	The Markdown files listed below: Core (routing, loading, content roles) and Memory (what's worth remembering).	Yes. This is Open Forge.
Extensions	Optional packages of more files: planning records, workflows, templates, project documents.	No. Install the ones that fit.
CLI	The `open-forge` command. It finds context, keeps navigation correct, and installs or updates files.	No. Everything it does, you can do by editing files.

How it fits together

Everything in the workspace answers one of two questions:

Core: how should this work be done? Six roles, because a rule, a piece of advice, a reusable shape, a capability, a starting file, and a pointer each behave differently. A rule must be followed. Advice can be adapted. A Template is copied and then owned by you. Keeping them apart is what lets an agent know how seriously to take each file.
Memory: what is worth remembering? Four states, because "where I am right now", "something I noticed", "what we accepted", and "what used to be true" deserve different trust. The rules tell an agent to treat Crystallized knowledge as current and Emerging findings as unconfirmed. Archived history doesn't control current work.

The Concepts section covers each part in depth.

See the full framework map

At startup your agent reads its instructions, most main folder indexes, and the files their tags or rules require. Everything else opens when a task needs it.

Startup reads your agent instructions, the loader, installed entrypoints tagged to load, and required files such as the CLI usage Skill. Your setup determines the footprint.

AGENTS.md or CLAUDE.mdYour agent tool reads it automatically. It points to the loader.

.agents/loader.mdRead next, in full: the loading rules and the main folders.

An entrypoint is a folder's index file: its purpose, its rules, and one line per entry. Linked files open when selected, tagged to load, or required by a loaded rule.

Core How to work

DirectivesRules that must be followedEntrypoint at startup
Root rules: at startupScoped rules: when their scope is selectedFor example: run the tests before calling work done.
GuidanceAdvice for choices that keep coming upEntrypoint at startup
Linked files: when selected or requiredFor example: when to split a module.Extensions add Adaptive Collaboration.
PatternsReusable shapes that make work easy to create and checkEntrypoint at startup
Linked files: when selected or requiredFor example: the shape of an API error.Extensions add Work Records.
SkillsCapabilities packaged as SKILL.mdEntrypoint at startup
CLI usage Skill: required at startupOther Skills: when selectedFor example: a code review Skill.Starts with open-forge-cli. Extensions add use-workflow.
TemplatesStarter files to copy and adaptEntrypoint on demand
Linked files: when selected or requiredFor example: a Decision starter.Most Extensions add starters.
MapsPointers to important sourcesEntrypoint at startup
Linked files: when selected or requiredFor example: your ADRs, wiki, or API docs.

Memory What to remember

Entrypoint at startup

These are places to keep material, not required steps. A record can start in any state that fits it. Accepted knowledge can go straight to Crystallized.

Working NowTemporary state for work in progress.Entrypoint at startup
Linked files: when selected or requiredExtensions add Checkpoints and Handoffs.
Emerging MaybeUseful material nobody has accepted yet.Entrypoint at startupAlso re-read at refresh points.
Linked files: when selected or requiredExtensions add Ideas, Analysis, and Observations.
Crystallized True nowAccepted knowledge that stays current.Entrypoint at startup
Linked files: when selected or requiredExtensions add Decisions and Documents.
Archived HistoryKept for reference. It no longer governs current work.Entrypoint on demand
Linked files: when selected or required

Possible moves: Working to Emerging when worth keeping but not settled. Emerging to Crystallized when accepted. Crystallized to Archived when replaced. Memory rules.

Read the startup files
Open what the task needs
Do the work
Save what's worth keeping

How loading works

Linked files open when selected or required. #LoadNow reads a file when its parent index loads. #KeepInMind also re-reads it at task start or resume, after a context restore, and before handoff or closeout while its scope is active. Both tags act through a loaded parent. The Skills rules explicitly require the CLI usage guide at startup.

A file with applyTo patterns applies only while the task works on a matching file.

open-forge context skills/open-forge-cli batches the default loading-tag closure and the required CLI guide. Extensions are optional packages you add.

What you actually install

Full Core supplies 19 Markdown files, including four supporting CLI guides that are opened when needed. Essentials includes Directives, Patterns, Skills, Emerging and Crystallized Memory, plus Working Memory. Custom follows your selection.

Essentials keeps new Working records out of ordinary Git commits and leaves _working.md eligible for sharing. Already tracked files stay tracked. Generated Entries omit private contents. You can find and read local records with the CLI or your normal file tools. Installation covers the exact choices.

See the Full Core files and startup details

AGENTS.md                         <- tells the agent to read the loader first
CLAUDE.md                         <- bridge for harnesses that read CLAUDE.md
.agents/
  loader.md                       <- routing and loading rules, and the root routes
  directives/_directives.md       <- required behavior
  guidance/_guidance.md           <- advice for recurring choices
  patterns/_patterns.md           <- reusable shapes for code, files, and documents
  skills/_skills.md               <- native SKILL.md capabilities
  skills/open-forge-cli/SKILL.md  <- how to use the CLI, read at startup
  skills/open-forge-cli/references/
    discovery.md                  <- reading and discovery
    routes.md                     <- route maintenance
    packages.md                   <- Framework and packages
    common.md                     <- shared options and results
  templates/_templates.md         <- copy-ready starting files
  maps/_maps.md                   <- pointers to important local and external sources
  memory/
    _memory.md                    <- what is worth remembering
    working/_working.md           <- temporary state for active work
    emerging/_emerging.md         <- useful, but not settled yet
    crystallized/_crystallized.md <- accepted knowledge that stays current
    archived/_archived.md         <- history that no longer governs current work

Apart from Memory state entrypoints and one Skill that teaches agents the CLI, every selected category starts empty. The content comes from your work, such as a correction you keep repeating or a decision you don't want to explain again, and from any Extensions you install. Decisions, Checkpoints, workflow recipes, and starter Templates all come from Extensions, not from the base.

In Full Core, startup reads AGENTS.md, the loader, nine entrypoints, and the CLI usage Skill required by Skills. Essentials and Custom use the same loading rules for the routes present. Reading an entrypoint doesn't load everything it lists. Other items open when selected, tagged to load, or required by a loaded rule. Loading and tags has the full table.

Where to go next

New here? Follow Installation, then the ten-minute guide. New or existing project covers what to write down first in each case.
Want to see it work? Try a demo: build a small app from an idea, or add a feature to a half-built one.
Wondering what's worth your attention? The Highlights pick out the features that do the most work for particular kinds of users, starting with Decisions.
Want to understand how it works? Read the Concepts, starting with Routing.
Wondering what an Extension actually puts in your workspace? The Extensions section explains every package file by file.
Using the CLI? Working with the CLI shows which command helps with which job, and the CLI reference covers every option.

Start using it​

The basic flow​

Three parts, one of them required​

How it fits together​