created_at: 2026-09-12T23:10:01Z updated_at: 2026-09-12T23:10:01Z created_by: nick modified_by: nick

AGENTS.md

This file provides guidance to agent / engineers when working with code in this repository.

Repository Authority

1. The operator's instructions for the current task have the highest authority.
2. Except for operator instructions, this AGENTS.md file is the primary repository authority.

Creating Markdown Files

These defaults apply throughout the project unless the operator or another applicable authority document instructs differently. Preserve established fixed filenames such as AGENTS.md, README.md, and named authority or workflow files.

Filenames

The default naming pattern should be

• prefix date using the YYYYMMDD_ format
• descriptive name in lowercase
• use "_" in place of spaces
• end new Markdown filenames with _v##, starting at _v01 and incrementing through _v99

YAML frontmatter

Every generated .md file will begin with a YAML frontmatter block delimited by --- lines containing exactly these four keys:

---
created_at: YYYY-MM-DDTHH:MM:SSZ
updated_at: YYYY-MM-DDTHH:MM:SSZ
created_by: <agent name> (<model>) <machine>
modified_by: <agent name> (<model>) <machine>
---

Rules:

• created_at / updated_at are UTC timestamps in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Use a 24-hour clock and include zero-padded hours, minutes, and seconds; the trailing Z identifies UTC.
• created_at is set once, at file creation, and MUST NEVER be modified on later edits.
• updated_at is rewritten to the current UTC timestamp on every modification.
• created_by is set once, at file creation, and MUST NEVER be modified on later edits.
• modified_by is rewritten on every modification. On the very first write, set it to the same value as created_by.
• The created_by / modified_by value uses the format <agent name> (<model>) <machine>, lowercase only, with no email addresses and no angle brackets. The machine is mandatory so the operator can identify which host wrote the file.

Acceptable examples:

created_by: claude (opus-4.7) macbook-air
created_by: codex (gpt-5.5) fsdc-avatar09
modified_by: claude (haiku-4.5) macbook-air

Archive Subfolder

• Really old docs are moved into docs/archive/.
• Organized into per-month subfolders named YYYYMM/ (e.g. 202604/).
• Not every month will have a folder — only months with archived files exist.
• Usually managed by the operator, not the AI coding agent.
• Agents: these files are kept for reference only; do not review them when scanning the project to build context.

Human-readable documents

Treat these as strong operator preferences rather than strict requirements. If they conflict with a requested document structure, template, or established heading hierarchy, preserve the intended structure and adapt these preferences to fit.

• Use plain, human-readable language.
• Do not use bold text.
• Prefer bullets and numbering over long paragraphs.
• Keep each paragraph under 50 words.
• Multiple short paragraphs are acceptable.
• Keep sections focused and easy for the operator to scan and answer.

Open questions created by agents

Use an open-questions section when the operator asks for one or when unresolved decisions would materially help the document.

• Make open questions the final section of the PRD, plan, or other agent-authored document.
• Use ## Open Questions as the section heading.
• If the document's required structure uses different heading levels, adjust the hierarchy while preserving the pattern below.
• Give each question its own numbered ### heading.
• Keep the numbered question heading description to 40 characters or fewer.
• Put the full question below its heading.
• Focus each question on one decision.
• Bullets are acceptable when they make choices or context easier to scan.
• Add a #### Operator Response subsection under every question.
• Leave the operator response empty unless an agent recommendation would be useful.
• When providing a recommendation, begin it with the agent's name in parentheses.
• Prefer recommendations under 30 words.
• Apply the human-readable document preferences to questions and recommendations.

Example:

## Open Questions

### 1. Default date range

Should a report without dates cover the trailing seven days, including today?

#### Operator Response

(codex) Recommend the trailing seven days in the Toggl user timezone.

Project Goal

Organize the operator's Medi-Cal documents, conversations, and notes so an AI agent can use the operator's content to help them navigate Medi-Cal and the health care ecosystem.

• Help manage paperwork, understand notices, arrange appointments, update forms, and track follow-up tasks.
• Keep original sources, factual records, and derived products organized and available as working context.

Folder Structure

• Use three main content folders: inbox/, references/, and generated_output/.
• Keep project guidance and documentation in AGENTS.md and docs/.
• The filenames below illustrate content placement. Follow the naming rules in AGENTS.md, except for PDF conversions, which must mirror the source basename as specified below.

AdminMediCal02/
├── AGENTS.md
├── docs/
│   └── archive/
│       └── YYYYMM/
├── inbox/
│   └── 2026/09/
│       └── 20260909_county_notice.pdf
├── references/
│   └── 2026/09/
│       ├── 20260909_county_notice.md
│       ├── 20260909_call_note_v01.md
│       ├── 20260909_online_action_v01.md
│       └── 20260909_user_notes_v01.md
└── generated_output/
    ├── draft/
    └── sent_completed/

Folder Responsibilities

1. inbox/: Store original PDFs, scanned mail, and online downloads under YYYY/MM, using two-digit months. Retain originals after processing.
2. references/: Store a full Markdown conversion of every incoming PDF, mirroring its YYYY/MM path and basename. Also store user notes, factual conversation and call records, and online action records, whether authored by the operator or an agent.
3. generated_output/: Store derived summaries, letters, call scripts, checklists, and other agent products. Use draft/ for drafts and sent_completed/ for sent or completed products.
4. docs/archive/YYYYMM/: Store retired project documentation by month, following AGENTS.md. Archived documents are historical references, not active instructions.

• After intake is processed, references/ and generated_output/ together provide recorded working context.
• Place factual records in references/ based on their purpose, even when an agent writes them.

Reading and Intake Policy

1. At startup, read the authority documents: AGENTS.md.
2. Read other files only when an authority document explicitly directs that reading under the applicable conditions, or when the operator directs inspection for the current task. A folder description, example filename, or incidental link does not authorize intake.