Codex Project Setup Guide

your-project/
├── AGENTS.md                 # Main instructions (auto-loaded by Codex)
├── .agents/
│   └── skills/
│       ├── run-tests/
│       │   └── SKILL.md      # Reusable procedure
│       └── deploy/
│           └── SKILL.md      # Reusable procedure
├── services/
│   └── payments/
│       └── AGENTS.md         # Nested override for this subdir
└── ~/.codex/
    └── AGENTS.md             # Global instructions (across all projects)

# AGENTS.md — Project Instructions

Codex reads this file before any work. Keep it small and durable —
push deep workflows into Skills under `.agents/skills/`.

## Discovery (how Codex layers context)
1. **Global:** `~/.codex/AGENTS.override.md` (if present), else `~/.codex/AGENTS.md`
2. **Project:** root → CWD, walking down. Each directory: `AGENTS.override.md` → `AGENTS.md`
3. **Merge:** files closer to your CWD override earlier guidance

## Meta-Learning Protocol
You operate under The Learner Brain methodology. Improve the *system*, not just the output.

### Triggers
1. **Repetition** — same correction twice
2. **Friction** — a workaround the user shouldn't repeat
3. **Manual labor** — multi-step task that should become a Skill
4. **Preference** — codify expressed style or approach

### Upgrade Format
```
🧠 BRAIN UPGRADE PROPOSAL
Trigger: [what caused this]
Surface: [AGENTS.md | Skill | Hook]
Location: [path]
Proposed change: [exact addition]
Rationale: [why it prevents future friction]
```

## Project Context
- Language: [Your language]
- Framework: [Your framework]
- Test command: [pnpm test | bun test | etc.]

## Working Agreements
- Run lint + tests before claiming a task is done
- Never commit `.env*` or anything under `secrets/`
- Propose ONE upgrade at a time and wait for approval

---
name: run-tests
description: Run the project's full test suite, summarize failures, and propose a fix plan. Use when the user asks for tests, verification, or coverage.
---

# Run Tests Skill

## When to use
- Before completing a task
- When the user says "run tests" / "verify" / "check"

## Steps
1. Detect package manager (pnpm > bun > npm)
2. Run the test command
3. If failures: group by file, summarize root cause, propose smallest fix
4. If passing: report counts and exit

## Outputs
- A short summary (✅ N passed | ❌ M failed)
- Proposed next action