Skip to content

README.md

Latest commit

 

History

History
340 lines (250 loc) · 10.8 KB

README.md

File metadata and controls

340 lines (250 loc) · 10.8 KB

Codex Context Agents logo

Codex Context Agents

~/.config/codex-agents is a files-first, git-backed state layer for Codex.

It centralizes:

  • agent operating policy
  • reusable skills
  • persistent memory

The goal is deterministic behavior with safe rollback.

Official Codex Docs

Why This Repo Exists

Without a state layer, agents tend to:

  • repeat decisions
  • lose project continuity
  • produce inconsistent runbooks
  • drift from agreed constraints

This repository fixes that by making durable state explicit, structured, and versioned.

Source of Truth and Symlink Model

Authoritative state lives in this repo.

Codex-facing paths should be symlinks:

  • ~/.codex/AGENTS.md -> ~/.config/codex-agents/AGENTS.md
  • ~/.codex/skills -> ~/.config/codex-agents/skills

This keeps Codex integration stable while all real state stays git-managed.

Repository Layout

~/.config/codex-agents/
├── AGENTS.md
├── README.md
├── lib/
│   └── secret_scan.sh
├── memory/
│   ├── README.md
│   ├── index.md
│   ├── logs/
│   ├── decisions/
│   ├── projects/
│   ├── knowledge/
│   └── patterns/
├── skills/
│   ├── decision-check/
│   ├── context-bootstrap/
│   ├── decision-record/
│   ├── memory-index-update/
│   ├── memory-retrieve/
│   ├── memory-write/
│   ├── project-status/
│   ├── project-update/
│   ├── workflow-plan/
│   ├── runbook-create/
│   ├── secret-scan/
│   ├── security-best-practices/
│   └── gh-address-comments/
├── bin/
│   ├── doctor.sh
│   └── install.sh
└── templates/

Operating Model

1) Read Before Recommend

Before architecture/workflow recommendations:

  1. Read memory/index.md.
  2. Check relevant decisions and project context.
  3. Summarize constraints before proposing changes.

2) Decision Enforcement

Use decision-check before architecture/workflow changes.

If relevant decisions exist, they are constraints, not suggestions.

3) Append-Only Discipline

  • logs and project logs: append-only
  • decisions: immutable (new file when superseding)
  • index: additive, minimal diff, no aggressive reordering

4) Automatic Index Hygiene

Index discoverability is now default behavior at creation time:

  • workflow-plan --to-pattern: auto-registers the new pattern plan in memory/index.md (## Patterns)
  • project-update: when first scaffolding overview.md, auto-registers under ## Projects
  • memory-write: when creating new project, knowledge, or pattern docs, auto-registers under the mapped section

All of the above route index writes through:

  • skills/memory-index-update/scripts/update_index.sh

If automatic index update cannot run, scripts print the exact fallback command to execute manually.

5) Strict Secret Policy

All write-side memory scripts enforce shared secret scanning.

Default behavior:

  • high-confidence secrets: block write
  • low-confidence secret-like content: redact and continue

Override (explicit):

  • --allow-redact allows blocked writes to proceed with in-place redaction

Shared scanner library:

  • lib/secret_scan.sh

Skill Catalog

Each skill has:

  • SKILL.md contract
  • optional scripts/ executables

Primary memory/continuity skills:

Skill Purpose Script
context-bootstrap Mandatory first pass for non-trivial tasks; orchestrates decision-check + project-status + memory-retrieve into one compact Context block skills/context-bootstrap/scripts/bootstrap.sh
decision-check Find applicable prior decisions before recommending changes skills/decision-check/scripts/check.sh
decision-record Create immutable one-decision-per-file records skills/decision-record/scripts/record.sh
memory-retrieve Pull minimal relevant memory context skills/memory-retrieve/scripts/retrieve.sh
memory-write Generic structured memory writer with automatic index registration for new anchors skills/memory-write/scripts/write.sh
memory-index-update Keep memory/index.md discoverable and idempotent skills/memory-index-update/scripts/update_index.sh
project-status Summarize project state from overview + log skills/project-status/scripts/status.sh
project-update Append structured project log updates and auto-index first-time project scaffolding skills/project-update/scripts/update.sh
workflow-plan Generate executable plan artifacts with verification + rollback (auto-index in --to-pattern mode) skills/workflow-plan/scripts/plan.sh
runbook-create Create reusable pattern/runbook docs and index them skills/runbook-create/scripts/create.sh
secret-scan Standalone pass/redact/block scanner utility skills/secret-scan/scripts/scan.sh

Additional utility skills:

  • security-best-practices
  • gh-address-comments

Memory Data Model

Memory root: memory/

  • README.md: operational conventions for cadence, naming, and index policy
  • index.md: table of contents for durable anchors
  • logs/: chronological notes
  • decisions/: architectural/workflow constraints
  • projects/: continuity (overview.md + log.md per project)
  • knowledge/: stable reference notes
  • patterns/: reusable procedures/runbooks

Quickstart

1) Install symlinks and run health checks

bin/install.sh

bin/install.sh runs bin/doctor.sh by default after symlink reconciliation.

2) Run doctor explicitly (optional but recommended in CI and troubleshooting)

bin/doctor.sh

3) Manual fallback symlink commands (if needed)

ln -sfn ~/.config/codex-agents/AGENTS.md ~/.codex/AGENTS.md
ln -sfn ~/.config/codex-agents/skills ~/.codex/skills

4) Validate shell scripts

bash -n \
  bin/install.sh \
  bin/doctor.sh \
  lib/secret_scan.sh \
  skills/secret-scan/scripts/scan.sh \
  skills/memory-retrieve/scripts/retrieve.sh \
  skills/memory-write/scripts/write.sh \
  skills/decision-check/scripts/check.sh \
  skills/decision-record/scripts/record.sh \
  skills/project-status/scripts/status.sh \
  skills/project-update/scripts/update.sh \
  skills/memory-index-update/scripts/update_index.sh \
  skills/workflow-plan/scripts/plan.sh \
  skills/runbook-create/scripts/create.sh

5) Run in temp memory for safe testing

TMP_ROOT="$(mktemp -d)"
export MEMORY_ROOT="$TMP_ROOT/memory"
mkdir -p "$MEMORY_ROOT"

Operator Workflow

  • Use bin/install.sh to reconcile expected symlinks with backup-and-replace safety.
  • Use bin/doctor.sh to detect drift; it exits non-zero when checks fail.
  • Prefer bin/install.sh --dry-run before first-time setup on unknown machines.
  • Use bin/install.sh --skip-doctor only when sequencing setup manually.

Common Workflows

Check decisions before proposing architecture

skills/decision-check/scripts/check.sh "skills directory and symlinks"

Retrieve targeted context

skills/memory-retrieve/scripts/retrieve.sh "codex-agents current status" \
  --scopes projects,decisions \
  --project codex-agents

Create a project execution plan

skills/workflow-plan/scripts/plan.sh \
  --goal "Implement deterministic retrieval ranking" \
  --project "codex-agents" \
  --constraints "append-only logs,minimal diffs" \
  --acceptance-criteria "tests pass,rollback documented"

Pattern mode (--to-pattern) also updates memory/index.md automatically.

Append project continuity update

skills/project-update/scripts/update.sh \
  --project "codex-agents" \
  --title "Implemented workflow-plan" \
  --status "in progress" \
  --notes "Added script and report contract" \
  --next "Implement runbook-create,Run smoke tests"

If this is the first update for a project and scaffolding is created, index registration is automatic.

Write durable knowledge with automatic index registration

skills/memory-write/scripts/write.sh \
  --type knowledge \
  --title "Token handling" \
  --body "Prefer env vars or secret manager; never commit credentials."

New knowledge/pattern/project anchors are auto-indexed through memory-index-update.

Create a reusable runbook and index it

skills/runbook-create/scripts/create.sh \
  --title "Release Cutover" \
  --when-to-use "When promoting a tested candidate to production" \
  --steps "Validate artifacts,Deploy canary,Promote" \
  --verification "Smoke tests pass,No elevated error rate" \
  --failure-modes "Canary fails,Rollback incomplete"

Scan text for secrets before writing

skills/secret-scan/scripts/scan.sh --text "token=abc123" --mode write

Secret Enforcement Details

Exit code conventions for secret-scan:

  • 0: pass or redacted
  • 3: blocked
  • 2: argument/validation error

Write-side scripts inherit the same policy and support --allow-redact.

Contribution Guidelines

  1. Keep behavior deterministic and auditable.
  2. Favor append-only updates for logs/project logs.
  3. Never silently mutate prior decision files.
  4. Keep index updates idempotent and minimal-diff.
  5. Use relative memory paths in script reports.
  6. Do not commit secrets; redaction is required.

Template-Safe Memory Tracking

This repository is intended to be shareable, so personal memory entries are ignored by default.

  • .gitignore ignores memory/** content to avoid committing local logs, decisions, project notes, or knowledge entries by accident.
  • The memory scaffold stays tracked: memory/README.md, memory/index.md, directory structure, and .gitkeep placeholders.
  • Result: collaborators can clone a clean, reusable agent state layer while each user keeps private/local memory history out of git.

If you intentionally want to publish durable memory artifacts, add files explicitly with git add -f <path> and review them carefully before commit.

Git Workflow

Typical cycle:

git status
git add <files>
git commit -m "feat(...): ..."

Rollback is straightforward because state is file-based and versioned.

Relationship to AGENTS.md

AGENTS.md is the runtime operating policy for agents.

README.md is the human/operator guide for understanding and contributing to this repository.

If there is ambiguity, follow AGENTS.md for behavior and update this README accordingly.