agentleFS
afain12afain12/coo-twin/AGENTS.md

coo-twin

AGENTS.md0 starsChanged 6 months agoMITView on GitHub

A personal Chief of Staff system that unifies Notion, Obsidian, Google Calendar, and Google Tasks into a single terminal workflow. The goal: replace opening four apps in the morning with one /start-day command, route every meeting's output to the right tool automatically, and never let work fall through the cracks overnight. New here? Read SETUP.md first. It walks you through token setup, config files, and your first /start-day. This file (AGENTS.md) is the canonical project context OpenAI Codex reads. Its…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository8 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

16 rules. About 0 are common, 6 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All paths above are relative to <repo_root>.

    line 68
  2. Very specific:

    IMPORTANT: Use the /v1/data_sources/{id}/query endpoint, NOT /v1/databases/{id}/query.

    line 77
  3. Very specific:

    Every item is assigned to a stream — the generic equivalent of departments, business units, or projects.

    line 120
  4. Very specific:

    Every actionable item gets a - [ ] checkbox.

    line 151
  5. Very specific:

    Before saying anything is "not in Notion," run /v1/search against a unique fragment (URL, person name, title keyword).

    line 185
  6. Very specific:

    When a skill prepares a Notion PATCH /v1/blocks/{id}/children payload that needs a trust gate or human review, it lands as a JSON file in …

    line 191
  7. Very specific:

    Every skill begins with MODE=$(scripts/check_mode.sh) || exit at Step 0.

    line 224
  8. Very specific:

    Never edit rows in place. A future /weekly-review skill reads this file to detect drift.

    line 233
  9. Very specific:

    Every external write (Notion PATCH, gtask insert, calendar event) carries an action_id of the form {skill}:{target}:{date}:{8-char-hash}.

    line 238
  10. Distinctive:

    Read-first, write-on-approval: Never auto-write without trust gate confirmation.

    line 283
  11. Distinctive:

    Graceful degradation: If any source is unavailable, run with what's available.

    line 285
  12. Very specific:

    Stream tagging: Every item tagged by stream using the Workspace field or keyword matching from streams.yaml.

    line 289
  13. Distinctive:

    Time-blocking: Don't just list tasks — offer to block calendar time for high-priority items.

    line 296
  14. Distinctive:

    All skills follow these patterns:

    line 304
  15. Distinctive:

    Empty response: Not an error — display "No items found in {database name}".

    line 313
  16. Distinctive:

    Keep the two bodies identical — when a project fact changes, update both.

    line 322

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

COO Twin — Daily Automation System

A personal Chief of Staff system that unifies Notion, Obsidian, Google Calendar, and Google Tasks into a single terminal workflow. The goal: replace opening four apps in the morning with one /start-day command, route every meeting's output to the right tool automatically, and never let work fall through the cracks overnight.

Getting Started

New here? Read SETUP.md first. It walks you through token setup, config files, and your first /start-day.

This file (AGENTS.md) is the canonical project context OpenAI Codex reads. Its sibling CLAUDE.md is the same content for Claude Code users — when a project fact changes, update both. Tool-specific operating notes live at the bottom of each file.

Skills

SkillPhaseDescription
/setup0Interactive bootstrap — detect sources, define streams, write config
/notion-probe0Read-only audit of your Notion workspace
/notion-map0Map probed DBs to canonical roles, write IDs to config/sources.yaml
/notion-template-install0Install the canonical 4-DB template into an empty workspace
/start-day1Morning briefing + daily plan
/capture-meeting2Meeting note splitter (Notion + Obsidian + Calendar)
/end-day3Day close retro, planned vs actual, carry-forwards

Project Structure

.claude/skills/
  setup/SKILL.md                — Interactive bootstrap
  notion-probe/SKILL.md         — Workspace audit
  notion-map/SKILL.md           — DB role mapping
  notion-template-install/SKILL.md — Canonical 4-DB installer
  start-day/SKILL.md            — Morning briefing
  capture-meeting/SKILL.md      — Meeting note routing
  end-day/SKILL.md              — Day close retro
templates/notion/               — Notion DB schemas used by /notion-template-install
config/
  streams.yaml                  — Your "departments" / business units (single source of truth)
  sources.yaml                  — Notion DB IDs, field mappings, source toggles
scripts/
  check_mode.sh                 — Reads state/coo_mode.yaml; called at every skill's Step 0
  telemetry.sh                  — Appends a row to logs/_telemetry.jsonl
  action_id.sh                  — Idempotency: generate / check / stamp action_ids
  phi_scan.sh                   — PHI input gate for /capture-meeting
state/
  coo_mode.yaml                 — System-wide write-mode (observe | draft | approved | auto | locked)
  priorities.yaml               — Carry-forward items between days (/end-day writes, /start-day reads)
  tmp/                          — Scratch JSON for curl payloads (don't commit)
.context/                       — Staged Notion block-children payloads (PATCH bodies)
  *.json                        — Top-level: pending. /start-day flags these.
  applied/                      — Move applied payloads here after PATCH succeeds.
logs/
  YYYY-MM-DD.md                 — Daily briefing + EOD retro logs
  _telemetry.jsonl              — Append-only one-row-per-run skill telemetry
vault/                          — Obsidian vault (point obsidian_vault_path at yours)
  inbox/                        — Fleeting notes, quick captures
  daily/                        — Daily notes (YYYY-MM-DD.md)
  meetings/                     — Meeting notes (created by /capture-meeting)
  notes/                        — Permanent / evergreen notes

All paths above are relative to <repo_root>.

Data Sources

Notion (REST API via curl)

Authentication: $NOTION_API_TOKEN env var (loaded from .env). API Version: 2025-09-03.

IMPORTANT: Use the /v1/data_sources/{id}/query endpoint, NOT /v1/databases/{id}/query. The data_source IDs are different from database IDs. All IDs live in config/sources.yaml — that's the single source of truth. Read from there rather than hard-coding.

Canonical roles: Master Tasks, Provider CRM (or generic Contacts/Accounts), Activity Log, Meeting Notes. You don't need all four — skills degrade gracefully if a role is unmapped.

Key fields on Master Tasks (defaults; override in config/sources.yaml):

  • Status (status): "Not started", "In progress", "Waiting", "Done"
  • Workspace (select): values match workspace_values in streams.yaml
  • Due (date): ISO date
  • Assignee (people): array of users
  • Task (title): task name

Overdue = Due date in the past AND Status != "Done" Stale = last_edited_time older than staleness_days AND Status != "Done"

Google Calendar (gws CLI)

gws calendar +agenda --today --format json     # Today's events
gws calendar +agenda --tomorrow --format json  # Tomorrow's for prep
gws calendar +insert --summary "..." --start ... --end ...   # Create event

Google Tasks (gws CLI)

gws tasks tasklists list                       # List all task lists
gws tasks tasks list --params '{"tasklist":"<id>"}'
gws tasks tasks patch ...                      # Use this for writes

Obsidian (direct file read/write)

Vault path: configured via obsidian_vault_path in config/sources.yaml. Set to null to disable Obsidian integration.

Streams (your "departments")

Every item is assigned to a stream — the generic equivalent of departments, business units, or projects. Streams are defined in config/streams.yaml and referenced everywhere else by key. Examples: work / personal, or team-a / team-b / team-c, or your business divisions.

Routing principle: the actual Workspace field on each Notion item is authoritative. Do NOT inherit a stream from a parent task's name, the containing page's title, or the database it lives in. If the Workspace field is null, infer from context using the keyword lists in streams.yaml. When keywords would match multiple streams, the first match in declaration order wins (so order matters — put the most specific streams first).

Daily Note Format

Daily notes in vault/daily/YYYY-MM-DD.md use stream-grouped checkboxes:

## Actionable Items by Stream

### <Stream display_name 1>
- [ ] Task with context

### <Stream display_name 2>
- [ ] Task with context

### Other / Personal
- [ ] Task with context

Rules:

  • Every actionable item gets a - [ ] checkbox.
  • Group by stream, NEVER by data source (no "Notion section" + "Tasks section" split).
  • Overdue and stale items go into their stream section, not a separate section.
  • Include a "Notion Changes (Last 24 hrs)" section: completed, created, edited.
  • Include an "End of Day Review" section: completed, carries forward, notes/decisions.
  • Include a "Backlog — Needs Triage" section for low-priority items not for today.

Information Routing

Three brains, three roles:

  • Notion → business system of record (tasks, CRM, activity logs, accounts).
  • Google Tasks → quick-capture to-dos with due dates.
  • Obsidian → reflections, learnings, process improvements.

Routing rules:

  • Action items with business context → Notion.
  • Quick reminders, errands → Google Tasks.
  • Reflections, learnings, process notes → Obsidian.
  • Meeting outcomes SPLIT: actions → Notion, learnings → Obsidian, follow-ups → Google Calendar / Tasks.
  • Decisions → Notion Activity Log (single source of truth); Obsidian gets a link, not a copy.

Search workspace-wide before declaring missing

Notion content can live in databases OR as block content inside topic pages. Before saying anything is "not in Notion," run /v1/search against a unique fragment (URL, person name, title keyword). Topic-page appends to existing pages are a legitimate landing pattern and won't appear in any database query.

Staged Notion writes (.context/ lifecycle)

When a skill prepares a Notion PATCH /v1/blocks/{id}/children payload that needs a trust gate or human review, it lands as a JSON file in .context/. The lifecycle is mandatory:

  1. Stage — write the {"children":[...]} payload to .context/<name>.json.
  2. Apply — PATCH the payload to Notion.
  3. Cleanup — immediately mv .context/<name>.json .context/applied/<name>-<YYYY-MM-DD>.json. The date is when the write landed, not when the file was created. Never leave applied payloads in .context/ top-level — /start-day's pre-flight will keep flagging them as pending writes.

/start-day only scans top-level .context/*.json, never .context/applied/.

Cross-cutting Agent Discipline

Five disciplines wired through every skill via four shared helpers and one state file. Every new skill MUST honor these patterns.

Operating mode — state/coo_mode.yaml

System-wide mode controls write behavior across all skills:

ModeBehavior
observeRead-only. No writes to any external system. Briefings still render.
draftDefault. Every write goes through a trust gate.
approvedTrust gate auto-approves action_ids whose prefix matches approved_action_prefixes. Others still gated.
autoFull auto for skills listed in auto_skills (empty by default).
lockedEmergency stop. Every skill refuses at Step 0.

Every skill begins with MODE=$(scripts/check_mode.sh) || exit at Step 0.

Telemetry — logs/_telemetry.jsonl

Append-only JSONL. One row per skill run. Written via scripts/telemetry.sh. Required fields per row: ts, skill, run_id, duration_ms, status. Each skill adds its own context (sources_ok, confidence buckets, write counts, mode, …).

Never edit rows in place. A future /weekly-review skill reads this file to detect drift.

Idempotency — scripts/action_id.sh + .context/applied/

Every external write (Notion PATCH, gtask insert, calendar event) carries an action_id of the form {skill}:{target}:{date}:{8-char-hash}. Before executing, skills call:

AID=$(scripts/action_id.sh generate <skill> <target> <date> <payload>)
scripts/action_id.sh check "$AID" && skip || run_write
# ... after success ...
scripts/action_id.sh stamp "$AID" '{"notion_page_id":"..."}'

Stamped action_ids live as JSON files in .context/applied/{aid}.json. Re-runs no-op. Failed writes are NOT stamped — they retry on next run.

PHI / sensitive-input gate — scripts/phi_scan.sh

/capture-meeting scans raw notes for SSN / DOB / MRN patterns BEFORE LLM parsing. Detection refuses the run and logs to logs/_phi_refusals.jsonl.

This is a cheap guardrail — it prevents the dumbest leakage (accidentally pasted patient identifier). It does NOT make the system compliant with any regulatory regime.

Confidence + source citation on routed items

/capture-meeting's trust gate shows per item: category + confidence score, the originating source line, and the action_id. Items with low confidence auto-route to Uncategorized regardless of indicator strength — better to hand-classify a few hard ones than yes/no a flood of easy ones.

Daily briefing source markers

/start-day renders a short source marker ([notion:abcd…], [gtask:xyzw…], [cal], [derived]) next to every Top 3 item — a 4-character ID stub for visibility plus a full HTML comment for /end-day's exact-ID sync.

Calendar Business Tagging

Events are auto-tagged from summary text using the per-stream keywords lists in config/streams.yaml. No match → untagged. First-match-wins in declaration order, so put the most specific streams first.

Key Principles

  1. Read-first, write-on-approval. Never auto-write without trust gate confirmation.
  2. Graceful degradation. If any source is unavailable, run with what's available. Never crash.
  3. Local state is primary. Config, logs, and state live in this repo, not in agent memory.
  4. Stream tagging. Every item tagged by stream using the Workspace field or keyword matching from streams.yaml.
  5. Route, don't dump. Parse streams of info into the right tool — don't pile everything in one place.
  6. Close the loop. /end-day scans all Notion DBs for today's changes, extracts next steps, routes to Tasks/Calendar. Nothing falls through the cracks overnight.
  7. Time-blocking. Don't just list tasks — offer to block calendar time for high-priority items. A task is a suggestion; a calendar block is a commitment.
  8. System evolves. Capture workflow improvements. Surface patterns proactively.

Error Handling Patterns

All skills follow these patterns:

  • Notion timeout: --max-time 60 on all curl calls.
  • Auth failure (401): Warn user to check NOTION_API_TOKEN, skip source.
  • Database not found (404): Warn to share DB with integration, skip source.
  • gws CLI failure: Skip Calendar/Tasks gracefully, suggest gws auth login --scopes calendar,tasks.
  • gws API not enabled (403): Warn to enable API in Google Cloud Console.
  • Empty response: Not an error — display "No items found in {database name}".
  • Never retry automatically. Report clearly and continue with available sources.

Codex Operating Notes

OpenAI Codex reads this file (AGENTS.md) as its canonical project memory at the start of every session. Claude Code reads the mirror file CLAUDE.md. Keep the two bodies identical — when a project fact changes, update both.

Tool-specific notes (sandbox config, approval modes, MCP servers, etc.) belong in this section so they don't drift into the shared body. Add yours as you discover them.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.