Skip to content

TODO: Agent Helpers (Non‑repo Project Context)

This document captures a proposed convention for keeping agent-specific project context and long-term “memory” out of the Git repository, while still making it consistently available inside containers.

Goals

  • Keep the checked-out repo root at /workspace for maximum compatibility with Codex / Claude Code / Vibe CLIs.
  • Store agent-owned files outside the repo (not committed, not mixed with source code).
  • Make project context durable across tasks (persistent “memory”), while allowing per-task overrides.
  • Standardize where reference code and runbooks live so agents can reliably find them.

Proposed container layout

The container has a single project repo at /workspace and a single agent context root at /agent.

/workspace/                 # Git repo root (what the agent edits)
/agent/                     # Non-repo agent context (mounted/generated)
  INSTRUCTIONS.md           # Project/container runbook (persistent)
  TASK.md                   # Task-specific instructions (ephemeral)
  memory/                   # Long-term memory (persistent, many small files)
    00-index.md
    architecture.md
    conventions.md
    pitfalls.md
    decisions.md
  runbooks/                 # Operational playbooks (persistent)
    build-and-test.md
    release.md
    migrations.md
    debugging.md
  reference/                # Optional read-only reference code (persistent)
    README.md               # What this is, how to use it
    ...                     # Zips expanded here, snapshots, rewrites, etc.
  skills/                   # Optional agent skills/playbooks (persistent)
    ...                     # Format/tooling is agent-dependent
  artifacts/                # Optional scratch outputs (ephemeral or persistent)
    ...                     # Logs, repro notes, generated reports

Notes: - Prefer many small files in /agent/memory/ rather than one huge file. - Keep /agent/reference/ read-only by convention; treat it like docs/examples, not a build input.

What goes where

Mounted from the host (shared folders; persistent across tasks)

Recommended to mount: - /agent/memory/ (long-term memory store) - /agent/runbooks/ (project playbooks; “how to operate this project”) - /agent/reference/ (optional, especially if large or shared across tasks) - /agent/skills/ (optional; if you curate skills outside the image) - /agent/INSTRUCTIONS.md (optional; if you want to edit per-project container guidance without rebuilding)

Should generally NOT be mounted from host: - Secrets themselves (API keys, tokens). Use agent-specific homes for auth material (e.g. ~/.claude, ~/.vibe/.env, ~/.codex) or env vars injected by the runtime.

Generated by the task runner (ephemeral per run)

Recommended to generate/overwrite: - /agent/TASK.md (acceptance criteria, scope limits, links, constraints for this run) - /agent/artifacts/ (if you want per-run outputs; can also be mounted if you want to keep them)

If you want to support “extra instructions” flags in a TUI/CLI, materialize them into /agent/TASK.md so all agents consume the same interface.

Provided by the project Dockerfile (image defaults)

Recommended to bake into the image: - Create the /agent/ directory structure (so paths always exist). - Provide empty placeholders (/agent/TASK.md, /agent/memory/00-index.md, etc.) to reduce conditional logic. - Provide a minimal /agent/INSTRUCTIONS.md (generic container basics) if you don’t mount a project-specific one.

How to “direct” each agent to /agent

Codex CLI

Codex can’t “import” other Markdown files the way Claude can; the simplest pattern is to instruct it (via ~/.codex/AGENTS.md or ~/.codex/AGENTS.override.md) to always read /agent/* before doing work.

Recommended approach: - Keep auth/config in ~/.codex/ (global). - Add a global rule in ~/.codex/AGENTS.md: - “Before doing any work, read /agent/INSTRUCTIONS.md, /agent/TASK.md (if present), and the relevant files under /agent/memory/ and /agent/runbooks/.”

If you want per-project automation without changing the global file, have the task runner generate ~/.codex/AGENTS.override.md for the container/session (note: it replaces the base file at the Codex-home level).

Claude Code

Claude supports importing additional files from CLAUDE.md using @/path/to/file syntax.

Recommended approach: - Keep auth/config in ~/.claude/ (global). - In ~/.claude/CLAUDE.md, import the project context: - @/agent/INSTRUCTIONS.md - @/agent/TASK.md - Optionally @/agent/memory/00-index.md (which can in turn reference the recommended memory files).

Mistral Vibe

Vibe loads user instructions from ~/.vibe/instructions.md (and can also use ./.vibe/instructions.md when a folder is “trusted”).

Recommended approach: - Keep auth/config in ~/.vibe/ (global). - Mount or symlink ~/.vibe/instructions.md to /agent/VIBE_INSTRUCTIONS.md (or directly to /agent/INSTRUCTIONS.md), and include a short bootstrap: - “At the start of each task, read /agent/INSTRUCTIONS.md and /agent/TASK.md, then consult /agent/memory/ and /agent/runbooks/ as needed.”

Conventions for /agent/memory/

Suggested file set (adjust per project): - 00-index.md: quick table-of-contents, what to update, “memory hygiene” rules - architecture.md: high-level system map - conventions.md: coding/testing conventions and “preferred commands” - pitfalls.md: known sharp edges and time-sinks - decisions.md: short decision log (agent-facing; separate from repo ADRs if desired)

Keep each file short and focused; prefer updating index links over growing a single page indefinitely.