Concepts

Open Forge is built on one idea: give agents a map of the workspace, not the whole workspace. Everything else follows from making that map cheap to read and easy to grow.

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.

1. Read the startup files
2. Open what the task needs
3. Do the work
4. 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.

Adaptive Context Engineering

Adaptive Context Engineering (ACE) combines two ideas that already work well:

• Progressive disclosure: show the next useful level of detail, not everything at once.
• Spec-driven development: make goals, constraints, and expected results explicit enough to guide the work and check the result.

ACE applies both to the workspace itself. A task starts from what you want to achieve. As the work progresses, the agent loads what it needs, such as the relevant architecture, your local conventions, or a decision you made last month. Unrelated history stays out. What you learn along the way can become part of your Framework, so the next task starts with it.

The pieces

Concept	In one sentence	Read more
Routing	Every routed folder has one short entrypoint that lists its direct children, so an agent navigates instead of scanning.	Routing
Scopes	A folder in a route can narrow where the content below it applies, so specialized rules load only for work that needs them.	Scopes
Loading tags	#LoadNow and #KeepInMind mark what is read as soon as its parent entrypoint loads. Everything else waits until a task selects it.	Loading and tags
Core categories	Six roles for content: Directives, Guidance, Patterns, Skills, Templates, and Maps.	Core categories
Memory	Four states for what's worth remembering: Working, Emerging, Crystallized, and Archived.	Memory
Customizing	Every installed file is yours. Edit it, replace it, remove it, or add an overwrite companion that updates leave alone.	Customizing

Two parts of the Framework

The Framework has two parts:

• Core defines routing, loading, and six reusable content roles.
• Memory keeps useful context as the work evolves, in four states.

Full Core supplies 19 Framework Markdown files. They include AGENTS.md, CLAUDE.md, the loader, six Core category entrypoints, five Memory entrypoints, and the open-forge-cli Skill with its four reference files. Essentials and Custom follow your installation choices. The CLI also keeps settings and an ownership record for maintenance. Records such as Decisions, Documents, and Checkpoints, workflow recipes, and starter Templates come from an Extension or from you.

Methods for planning, development, project documents, or coordinating several agents are optional Extensions. You install the ones that fit your work and skip the rest.

Why plain Markdown

AI made code cheap to write, and review became the bottleneck. The framework you work in should be easy to read, diff, and version with the rest of your project. There's no hidden database, no agent runtime, and no dependency on one vendor.

It's small on purpose too. Big predefined methodologies assume everyone works the same way, and nobody does. Open Forge gives you a handful of rules and a structure you can grow through scopes, then leaves the rest to you.

The files are the source of truth

This site helps you get acquainted. The rules an agent follows live in the installed files themselves, starting with loader.md. When this site and your installed files disagree, the files win.

Next: Routing.