Agentic-AssetsAgentic-Assets/apple-mail-mcp/tasks/CLAUDE.md

apple-mail-mcp / tasks

CLAUDE.md0 starsChanged 4 months agoMITView on GitHub

Cross-session planning artifacts. In-conversation work uses ephemeral task lists; this folder survives between sessions. Agents MUST read this file and todo.md before creating or moving anything under tasks/. This repo is PUBLIC. Research notes, handoffs, and measurement writeups land here, and they are world-readable on push. Measured numbers are publishable; the mailboxes behind them are not. Keep out real addresses, subjects, account UUIDs, absolute /Users/... paths, and session scratch paths or session IDs. See root AGENTS.md § This repo is…

In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apple-mail-mcpb/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .claude-plugin/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- tools/CLAUDE.mdCLAUDE.md
- apple-mail-archive-exportSkill
- context-guidance-auditSkill
- cowork-plugin-customizerSkill
- create-cowork-pluginSkill
- finalize-apple-mail-mcpSkill
- find-skillsSkill
- mail-scripting-dictionarySkill
- marketplace-release-handoffSkill
- mcp-builderSkill
- plugin-creatorSkill
- plugin-settingsSkill
- plugin-structureSkill
- python-performance-optimizationSkill
- reviewing-codeSkill
- testing-pythonSkill
- thermo-nuclear-code-quality-reviewSkill

The file

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

9 rules. About 0 are common, 0 are distinctive, and 9 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Every coding agent working in this repo must follow the tasks/ layout.
line 11
Very specific:
Add one line to archive/README.md.
line 39
Very specific:
Remove the row from Active in INDEX.md (or mark Reference/Archive).
line 40
Very specific:
Use full bucket paths: tasks/active/..., tasks/reference/..., tasks/archive/....
line 47
Very specific:
When executing reference/apple-mail-plugin-robustness-goal-2026-05-22.md, reference/phase-plan-3.1.7.md, or todo.md:
line 61
Very specific:
Use cayman@agenticassets.ai for perf gates (194 mailboxes).
line 89
Very specific:
After tools/*.py: .venv/bin/pytest tests/ -q (count single-sourced in tools/expected_test_count.txt)
line 100
Very specific:
After manifests/package/artifact changes: bash tools/gates/dev-check.sh release + plugin-dev:plugin-validator when available
line 101
Very specific:
After skills: plugin-dev:skill-reviewer when available (+ manifest validator if marketing copy changed)
line 102

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 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.

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

Files

CLAUDE.md

tasks/ — planning and backlog

Cross-session planning artifacts. In-conversation work uses ephemeral task lists; this folder survives between sessions.

Agents MUST read this file and todo.md before creating or moving anything under tasks/.

This repo is PUBLIC. Research notes, handoffs, and measurement writeups land here, and they are world-readable on push. Measured numbers are publishable; the mailboxes behind them are not. Keep out real addresses, subjects, account UUIDs, absolute /Users/... paths, and session scratch paths or session IDs. See root AGENTS.md § This repo is PUBLIC.

Agent requirements (mandatory)

Every coding agent working in this repo must follow the tasks/ layout. GitHub-hosted Actions are disabled (see tests/CLAUDE.md § Local gates vs live Mail), so enforcement is local: the checked-in pre-commit hook runs tools/gates/pre-commit-validate.sh → bash tools/gates/dev-check.sh default, which runs tools/validators/validate_tasks_layout.py; tests/infra/test_tasks_layout.py enforces the same rule in pytest.

Read order

todo.md — see tasks/todo.md — current branch, active workstream, next action
INDEX.md — see tasks/INDEX.md — browse active/, reference/, archive/
This file — placement rules below

Layout (only these buckets)

Path	Put here	Do not
Root (`tasks/`)	`CLAUDE.md`, `INDEX.md`, `todo.md` only	No loose `*.md`, no workstream folders at root
`active/`	Open workstreams from the last ~30 days; one subfolder per lane	Do not archive here; do not leave shipped lanes forever
`reference/`	Durable specs/backlogs still cited by code, CHANGELOG, or docs	Do not dump ephemeral issue writeups here
`archive/`	Shipped, superseded, or resolved artifacts	Never edit for current work

When creating planning artifacts

New workstream — tasks/active/<short-name>/ with dated files (handoff-YYYY-MM-DD.md, phase-plan.md, etc.).
One-off issue tracker — tasks/active/<lane>/issue-<topic>-YYYY-MM-DD.md while open; move to tasks/archive/YYYY-MM/issues/ when resolved.
Durable design spec cited from code — tasks/reference/<name>.md only when it becomes long-lived policy.
Update todo.md — point at the active handoff under active/ (not a flat tasks/foo.md path).
Update INDEX.md — add or move the row when a lane opens, ships, or archives.

When shipping or superseding work

Move the folder or files to tasks/archive/YYYY-MM/ (shipped/ or issues/ subfolders as appropriate).
Add one line to archive/README.md.
Remove the row from Active in INDEX.md (or mark Reference/Archive).
Trim todo.md to the next active pointer.

Archive rule of thumb: ship/supersede, or older than ~30 days with no todo.md pointer.

Path references in code and docs

Use full bucket paths: tasks/active/..., tasks/reference/..., tasks/archive/.... Never reintroduce flat tasks/<dated-file>.md at the repo root of tasks/.

Layout

Path	Role
`INDEX.md`	Navigation index (active, reference, archive)
`todo.md`	Tiny active pointer
`active/`	Open workstreams
`reference/`	Durable specs and baselines cited by code/docs
`archive/`	Shipped or superseded artifacts

Agent orchestration

When executing reference/apple-mail-plugin-robustness-goal-2026-05-22.md, reference/phase-plan-3.1.7.md, or todo.md:

Subagents for research and implementation when available and permitted: delegate coding, tests, docs, and live runs; parallelize independent modules, sequence dependent phases. If the host or task lane forbids subagents, work directly and document that constraint.
Plugin-dev experts when available: plugin-dev:plugin-validator and plugin-dev:skill-reviewer agents; plus plugin-dev:mcp-integration, plugin-dev:plugin-structure, and mcp-builder skills per phase plan. If unavailable, run local validation and record the gap.

Active workstreams

The canonical list lives in INDEX.md § Active workstreams (single source; do not duplicate it here). The forward roadmap is reference/roadmap-2026-07-10.md.

Reference files

File	Role
`reference/roadmap-2026-07-10.md`	Forward roadmap (new tools/skills, enhancements, hardening, refusals)
`reference/id-first-refactor-spec.md`	Shipped ID-first design (v3.7.0)
`reference/phase-3-annotation-matrix.md`	Canonical tool-annotation matrix (`server.py` `ToolAnnotations` presets); cited from `plugin/apple_mail_mcp/tools/CLAUDE.md` § Add a tool
`reference/apple-mail-plugin-robustness-goal-2026-05-22.md`	Active robustness goal
`reference/robustness-backlog-2026-05-22.md`	Backlog sidecar
`reference/phase-plan-3.1.7.md`	Historical release sequencing
`reference/live-test-baseline-2026-05-21.md`	Live perf numbers
`reference/mcp-mailbox-timeout-audit-2026-05-22.md`	Timeout audit

Production test account

Use cayman@agenticassets.ai for perf gates (194 mailboxes). ai.openclaw is light regression only.

export DEFAULT_MAIL_ACCOUNT="cayman@agenticassets.ai"
.venv/bin/apple-mail perf-test --json   # routine core battery
# Heavy analysis only with explicit opt-in:
.venv/bin/apple-mail perf-test --include-analysis --allow-heavy-mail-scan --json

Maintenance

After tools/*.py: .venv/bin/pytest tests/ -q (count single-sourced in tools/expected_test_count.txt)
After manifests/package/artifact changes: bash tools/gates/dev-check.sh release + plugin-dev:plugin-validator when available
After skills: plugin-dev:skill-reviewer when available (+ manifest validator if marketing copy changed)
Module line budget: python3 tools/validators/check_module_line_budget.py (also in dev-check.sh + CI); refresh baseline only after intentional splits — docs/CLAUDE-conventions.md § Module line budget
Live workflow: docs/AGENT_LIVE_TESTING.md
Engineering rules: docs/CLAUDE-conventions.md

Root overview: CLAUDE.md → tasks/CLAUDE.md link in table

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.

Check your setup, free