workspace-memory: Instructions file for Codex

AGENTS.md — orientation for AI agents

If you are a human, you probably want README.md instead. This file is written for AI agents (Claude, GPT, Gemini, local models, etc.) who have been pointed at this repository and asked to help a human adopt or use the workspace-memory convention.

---

What this repository is

A documentation convention. Five markdown files per active project, plus a master orientation file at the workspace root, plus a reduced-form archive for completed projects. No code, no installer, no dependencies. The convention is described in detail in conventions.md; the templates to copy are in skeletons/; worked examples are in examples/.

The convention exists so that any project's current state, architecture, runbook, and decision history live in predictable locations with predictable names. This makes the project navigable to humans who haven't seen it in months and to AI agents who have never seen it at all.

What the human is likely asking you to do

One of three things, in roughly decreasing order of frequency:

1. Set up the convention in their workspace for the first time. They have an existing directory of projects (or are starting fresh) and want to adopt this layout. Your job is to scaffold the master AGENTS.md at their workspace root, create projects/active/ and projects/archive/ directories, and walk them through populating the first project. Do not try to populate every project at once — pick one with the human and do it well, then let them apply the pattern to the rest.

2. Add a new project to a workspace that already uses the convention. A master AGENTS.md already exists. Your job is to create projects/active/<slug>/ with the five-file skeleton, fill in what you can from the conversation, and update the project table in the master file. Confirm the slug with the human before creating directories — slugs are kebab-case, 2–50 chars, must start with a letter.

3. Migrate an existing project's docs into the convention. The human has scattered notes, READMEs, or partial docs and wants them organized into the five-file structure. Your job is to read what they have, sort it into the right files, and flag what's missing. Do not invent content to fill out sections you have no information for — leave TODO markers and tell the human what you'd need to know.