coo-twin
CLAUDE.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 (CLAUDE.md) is the canonical project context Claude Code reads at…
- Reads credentials
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- capture-meetingSkill
- end-daySkill
- notion-mapSkill
- notion-probeSkill
- notion-template-installSkill
- setupSkill
- start-daySkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
15 rules. About 0 are common, 5 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
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
- Very specific: line 67
All paths above are relative to <repo_root>.
- Very specific: line 76
IMPORTANT: Use the /v1/data_sources/{id}/query endpoint, NOT /v1/databases/{id}/query.
- Very specific: line 119
Every item is assigned to a stream — the generic equivalent of departments, business units, or projects.
- Very specific: line 150
Every actionable item gets a - [ ] checkbox.
- Very specific: line 184
Before saying anything is "not in Notion," run /v1/search against a unique fragment (URL, person name, title keyword).
- Very specific: line 190
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 …
- Very specific: line 223
Every skill begins with MODE=$(scripts/check_mode.sh) || exit at Step 0.
- Very specific: line 232
Never edit rows in place. A future /weekly-review skill reads this file to detect drift.
- Very specific: line 237
Every external write (Notion PATCH, gtask insert, calendar event) carries an action_id of the form {skill}:{target}:{date}:{8-char-hash}.
- Distinctive: line 282
Read-first, write-on-approval: Never auto-write without trust gate confirmation.
- Distinctive: line 284
Graceful degradation: If any source is unavailable, run with what's available.
- Very specific: line 288
Stream tagging: Every item tagged by stream using the Workspace field or keyword matching from streams.yaml.
- Distinctive: line 295
Time-blocking: Don't just list tasks — offer to block calendar time for high-priority items.
- Distinctive: line 303
All skills follow these patterns:
- Distinctive: line 312
Empty response: Not an error — display "No items found in {database name}".
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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.
Files
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 (CLAUDE.md) is the canonical project context Claude Code reads at
the start of every session. Its sibling AGENTS.md is the same
content for OpenAI Codex users — when a project fact changes, update both.
Skills
| Skill | Phase | Description |
/setup | 0 | Interactive bootstrap — detect sources, define streams, write config |
/notion-probe | 0 | Read-only audit of your Notion workspace |
/notion-map | 0 | Map probed DBs to canonical roles, write IDs to config/sources.yaml |
/notion-template-install | 0 | Install the canonical 4-DB template into an empty workspace |
/start-day | 1 | Morning briefing + daily plan |
/capture-meeting | 2 | Meeting note splitter (Notion + Obsidian + Calendar) |
/end-day | 3 | Day 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 notesAll 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_valuesinstreams.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 eventGoogle 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 writesObsidian (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 contextRules:
- 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:
- Stage — write the
{"children":[...]}payload to.context/<name>.json. - Apply — PATCH the payload to Notion.
- 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:
| Mode | Behavior |
observe | Read-only. No writes to any external system. Briefings still render. |
draft | Default. Every write goes through a trust gate. |
approved | Trust gate auto-approves action_ids whose prefix matches approved_action_prefixes. Others still gated. |
auto | Full auto for skills listed in auto_skills (empty by default). |
locked | Emergency 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
- Read-first, write-on-approval. Never auto-write without trust gate confirmation.
- Graceful degradation. If any source is unavailable, run with what's available. Never crash.
- Local state is primary. Config, logs, and state live in this repo, not in Claude memory.
- Stream tagging. Every item tagged by stream using the Workspace field
or keyword matching from
streams.yaml. - Route, don't dump. Parse streams of info into the right tool — don't pile everything in one place.
- Close the loop.
/end-dayscans all Notion DBs for today's changes, extracts next steps, routes to Tasks/Calendar. Nothing falls through the cracks overnight. - 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.
- System evolves. Capture workflow improvements. Surface patterns proactively.
Error Handling Patterns
All skills follow these patterns:
- Notion timeout:
--max-time 60on 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.
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
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.

