--- 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: ```yaml --- created_at: YYYY-MM-DDTHH:MM:SSZ updated_at: YYYY-MM-DDTHH:MM:SSZ created_by: () modified_by: () --- ``` 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 ` () `, 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: ```yaml 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: ```markdown ## 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. ```text 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/ ``` ## 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 directly in this folder. Do not create subfolders or other infrastructure unless the operator later requests it. 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. 3. When the operator mentions an `inbox/` file, first check for its matching Markdown conversion in `references/`, using the same relative path and basename. If present, read that conversion first. Inspect the original only when the conversion is missing, incomplete, ambiguous, or requires visual verification. This lookup and reading are authorized by the operator’s mention of the source file.