CTRL-FORGE

A repo that remembers what your AI forgot.

CTRL-FORGE is a durable project-memory system you copy into a private repository for real work.

IMPORTANT: THIS REPOSITORY IS PUBLIC.MShneur/ctrl-forge is the reusable template/system upstream, not a place for anyone's real projects. Do not put personal projects, manuscripts, research, private prompts, handoffs, production files, user/client data, credentials, API keys, tokens, or other private work anywhere in this repository.

Read REPO_MODE.yaml and PUBLIC_BOUNDARY.md before writing.

---

Public upstream vs. your private copy

The canonical upstream ships in:

mode: public-template-upstream

That mode stays locked here.

To use CTRL-FORGE for real work:

1. Click Use this template and create a Private repository.
2. Confirm the new repository is actually private.
3. In your private copy, edit REPO_MODE.yaml to:

mode: private-copy

4. Then keep your real work under mine/ in that private copy.

If your copy will be public, do not switch modes. Keep it template/example-only.

---

The basic layout

forge/ <- reusable system files
mine/ <- real work only in a private copy; synthetic examples only upstream

The public repository deliberately contains only reusable system material and explicitly allowlisted dummy/example content.

---

Start a private copy

After switching your private copy to mode: private-copy:

python tools/new_project.py "My First Project"

mine/projects/example-project/ is a synthetic worked example.

---

Public boundary enforcement

Canonical public CTRL-FORGE uses a repository-wide fail-closed allowlist. Arbitrary new root files/directories and real project paths such as projects/** are rejected unless intentionally reviewed as public system/template content.

Before any public contribution, run:

python tools/public_boundary_check.py
python tools/privacy_scan.py .

If either check is uncertain, do not publish the material.

---

Current-Handoff Control

CTRL-FORGE includes a reusable two-lane handoff protocol for projects with multiple AI sessions or workers: one lane for current handoffs and updates, one lane for project progress. See forge/handoff-control/README.md. Reusable private-copy improvements should be routed back upstream only after sanitization; personal choices stay as options. See forge/handoff-control/FORGE_IMPROVEMENT_ROUTING.md.

---

What the Librarian does

The Librarian routes work, catches duplicates, checks readiness, points to specialists, and writes handoffs. More in forge/agents/librarian.md.

---

Keeping a private copy updated

See UPDATING.md. Nothing auto-updates.

---

Honest limits

• Folders are not encryption. Real work belongs in a repository whose visibility is actually private.
• CI reduces accidental-publication risk but cannot recall data already copied, cloned, cached, or indexed.
• Never contribute private project content back to this public upstream.

---

Contributing

See CONTRIBUTING.md. Public contributions must contain reusable system/template material only.

---

The AI Duct Tape Collection

The future showed up early and forgot the manual. These are different strips of duct tape for the parts between “AI can do that” and “why am I still doing this by hand?”

• CTRL-FORGE(this repo) — The memory. Your AI forgot everything; the repo didn't.
• CTRL-AI — The governance. Evidence, dissent, uncertainty, and rules for how the AI behaves.
• R-Duck — The operator. Turns fuzzy intent into structured autonomous work.
• Agents of AI — The cast. Reusable agents, personas, workflows, techniques, teams, and failure modes.
• Ghost in the Loop — The handoff lane. Keeps multi-step AI work moving and exports/hands it off cleanly.
• Control Walkthrough — The hands. Finds the page, clicks safe buttons, fills boring fields, verifies the result, and gets out of the way.

Each project keeps its own license and security boundary. None of the public repositories are places to store credentials or private project data.

---

MIT licensed.