ForgeOS v1.20.1

An engineering operating system for governed software delivery.

Coding agents are good at writing code and bad at remembering why. ForgeOS gives them what a serious codebase already assumes: a durable project memory, write permissions a human opens deliberately, and validation that has to produce evidence before anything may be called done. The rules are not advice in a document — where it matters, a machine enforces them.

Get started Command overview

12 validation checks — 8 gating · 251 self-test cases per shell · 144 policy controls · Windows PowerShell 5.1 and POSIX bash, held identical by CI 

$ bash scripts/validation/check-all.sh

  structure       passed    gating
  policy          passed    gating      144 controls
  links           passed    gating      0 broken
  secrets         passed    gating      0 findings
  hook-selftest   passed    gating      251 cases
  ...
  VALIDATION PASSED: every gating check exited 0.

What it does today

Every capability below ships in v1.20.1 and is checked mechanically — nothing here is a promise. What changed in this release.

Operating contract

One authoritative rule set in the repository, loaded through thin adapters that are checked for duplication. Entry points are pointers, never rules of their own.

Project memory

Decisions, lessons, incidents, handoffs, and an open-questions register live as files in the repository — so a decision never survives only in a chat log.

Governance windows

Application paths stay closed until a human opens them. A narrow implementation window authorizes one slice of work, not the whole codebase — and it fails closed in every direction.

Safety hooks

Destructive commands, writes into an undefined project, and secret-shaped strings are refused before they run — with the reason, and with 251 self-test cases per shell proving the hooks still block what they must.

Lifecycle discipline

Work moves inbox → active → completed, and a closure gate refuses any task carrying unchecked criteria or placeholder review evidence.

Validation gates

Twelve checks — eight of them gating — run by one command, with identical behavior on Windows and POSIX enforced again in CI.

A preview that oversells is worse than one that waits. What is not yet proven is listed as not proven — the roadmap below names what is deliberately not built.

Install

Two ways in. Both end at the same place: your project carries the portable half of ForgeOS and passes its own validation suite. There is no curl-into-a-shell — ForgeOS's own safety hook refuses it.

From the release artifact — recommended

Download the archive and its checksum from the latest release, verify before you trust it, then sync into your project. The first sync is a dry run; review it, then apply. The same two steps upgrade a project that already adopted ForgeOS: files you customized are skipped, and your own records are never touched.

POSIX bash
sha256sum -c forgeos-1.20.1.tar.gz.sha256
tar -xzf forgeos-1.20.1.tar.gz
bash forgeos-1.20.1/scripts/blueprint/sync-blueprint.sh --source forgeos-1.20.1 --target <project>
bash forgeos-1.20.1/scripts/blueprint/sync-blueprint.sh --source forgeos-1.20.1 --target <project> --apply

Windows PowerShell
(Get-FileHash -Algorithm SHA256 forgeos-1.20.1.tar.gz).Hash
tar -xzf forgeos-1.20.1.tar.gz
powershell -NoProfile -ExecutionPolicy Bypass -File forgeos-1.20.1/scripts/blueprint/sync-blueprint.ps1 -Source forgeos-1.20.1 -Target <project>
powershell -NoProfile -ExecutionPolicy Bypass -File forgeos-1.20.1/scripts/blueprint/sync-blueprint.ps1 -Source forgeos-1.20.1 -Target <project> -Apply

From a clone

Start a new project from the repository itself — then make the history yours.

New project
git clone https://github.com/Anasabdellatif/forgeos.git my-project
cd my-project
rm -rf .git && git init -b main

Prepare a local forgeos command

The platform installers write a local command shim or launcher into a directory you choose. They fetch nothing, do not edit PATH, and verify a checksum when the source came from a release artifact.

POSIX installer
bash scripts/install/install-forgeos.sh --source <forgeos> --destination <tools-dir>
bash scripts/install/install-forgeos.sh --source <forgeos> --destination <tools-dir> --apply
<tools-dir>/forgeos doctor

Windows installer
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install/install-forgeos.ps1 -Source <forgeos> -Destination <tools-dir>
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install/install-forgeos.ps1 -Source <forgeos> -Destination <tools-dir> -Apply
<tools-dir>\forgeos.ps1 doctor

Then, in either case

The first run is expected to report unfilled markers: those are the facts your project must supply. The adoption step is the product — an unadopted blueprint gives structure with no knowledge.

Validate on POSIX
bash scripts/validation/check-all.sh

Validate on Windows
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/validation/check-all.ps1

No package managers yet — deliberately. Each channel is deferred on the roadmap with its blocker named. A local forgeos command and per-platform installer scripts ship in the repository, both proven on the platforms they claim.

Command overview

Reading commands answer. Writing commands dry-run by default and write only under --apply — and --force is never exposed.

The forgeos command

  • forgeos status Where the project is: state ledger, work, gates, validation, and next capability read-only
  • forgeos next The next safe slice of work, with a drafted governance window and a copyable prompt read-only
  • forgeos prompt The complete next-session package: scope, policy, reading order, validation plan, and a paste-ready prompt read-only
  • forgeos brief The same next-session package held to a strict size budget, measured by the command itself read-only
  • forgeos intake What kind of project this is, how ready it is, and which prompt family the next session belongs to read-only
  • forgeos doctor Prerequisite report: shell, JSON reader, git, hook wiring, line endings, and manifest read-only
  • forgeos version Which ForgeOS this is; an unknown release is reported unknown, never inferred read-only
  • forgeos adopt Bring ForgeOS into a project by delegating to sync-blueprint dry-run by default
  • forgeos update Refresh an adopted project; refuses a target that never adopted dry-run by default

Workflow commands

  • /discovery Define an undefined project — six phases, fires automatically
  • /adopt Fill the blueprint from an existing codebase
  • /start-task Turn a request into a bounded task with observable criteria
  • /implement Apply it as the smallest complete change
  • /review Independent correctness, safety, and evidence check
  • /finish-task Close only after the full Definition of Done
  • /handoff Continuation record for another session
  • /adr Record a durable decision
  • /build-context Package deterministic context for transfer
  • /blueprint-validate Run every check

Roadmap

What is not yet proven is listed as not proven. The full roadmap — including what is deliberately not being built — lives in the repository.

Now

Command layer and project intake

shipped
  • A command layer that answers the question asked at the start of a session: where is this project, and what is the next safe thing to do
  • Project ingestion — a project's own documents become compact, cited maps, read before implementation
  • A read-only intake report and readiness forecast that classify a project and name the next prompt family
  • Closure integrity and a self-measuring session brief (v1.20.0), then a self-test that returns the same verdict on any Windows console and a project-owned declaration of generated build outputs (v1.20.1)

Next

Real-project proof

in progress
  • Driving projects end to end through the full work loop, beyond the repository's own slices
  • Ingestion slice 2 — surfacing ingestion state through the command layer
  • Ingestion slice 3 — gating validation for a documented project with no maps, only once adopters have proven it

Later

Deliberately deferred

deferred
  • Package-manager channels — each deferred with its blocker named
  • A documented compatibility matrix of which adopted versions can upgrade to which — still outstanding
  • A read-only dashboard, only after the machine-readable status contract proves stable