apple-flow-ops

name	apple-flow-ops
description	Use when working on Apple Flow in the apple-flow repository. Enforces safe defaults, beginner-first startup, focused debugging, config hygiene, and required verification.

Codex Flow Ops

Overview

Use this skill for changes, debugging, and operations in the apple-flow repository.

Apple Flow is a local-first macOS daemon bridging iMessage, Mail, Reminders, Notes, and Calendar to Claude/Codex CLI. This skill keeps workflow safe-by-default and beginner-friendly while giving concrete operator steps.

When to Use

Use this skill when the task involves any of:

• Starting or troubleshooting the relay daemon
• Editing relay behavior in src/apple_flow/*
• Updating runtime config fields or .env.example
• Improving ingress/egress/orchestration/logging behavior
• Verifying safety gates around sender allowlist, chat prefix, or approvals

Non-Negotiable Safety Defaults

Keep these defaults unless the user explicitly asks otherwise:

• apple_flow_only_poll_allowed_senders=true
• apple_flow_require_chat_prefix=true
• apple_flow_chat_prefix=relay:
• apple_flow_process_historical_on_first_start=false
• apple_flow_notify_blocked_senders=false
• apple_flow_notify_rate_limited_senders=false
• Keep mutating workflows behind approval (task: and project:)

Do not remove duplicate/echo suppression without explicit request:

• apple_flow_suppress_duplicate_outbound_seconds
• IMessageEgress.was_recent_outbound(...)

Primary Workflow

1) Reproduce First

Use beginner path before changing code:

cd <path-to-apple-flow>
./scripts/start_beginner.sh

If startup appears idle, verify:

• Full Disk Access for terminal host app
• apple_flow_messages_db_path points to a real chat.db
• codex login is completed

2) Identify Root Cause

Inspect the right layer first:

• Runtime settings: src/apple_flow/config.py
• Polling/loop/logs: src/apple_flow/daemon.py
• Messages DB reads: src/apple_flow/ingress.py
• iMessage send and suppression: src/apple_flow/egress.py
• command routing and approvals: src/apple_flow/orchestrator.py

Prefer minimal, focused patches once the cause is clear.

3) Keep Config Hygiene

For every new config field:

1. Add sensible default in src/apple_flow/config.py
2. Document in README.md
3. Add sample in .env.example

If runtime behavior changes, update beginner-facing guidance:

• BEGINNER_SETUP_10_MIN.md

4) Preserve Logging Quality

Terminal logs should stay concise and actionable:

• Inbound row processed or ignored
• Explicit ignore reason (echo, missing prefix, empty, blocked, rate-limited)
• Handled command kind + duration

Avoid noisy repeated logs; keep throttled warnings for recurring failures.

5) Verify Before Completion

Run from repo root:

source .venv/bin/activate
pytest -q

Expected result:

• All tests passing

If tests fail, report failing tests and root cause before claiming completion.

Common Task Playbooks

A) Startup Failures

1. Run ./scripts/start_beginner.sh
2. Fix reported safety stop in .env (senders, DB path, placeholders)
3. Confirm Messages DB readability and Full Disk Access
4. Re-run script and confirm daemon foreground readiness

B) No Replies in iMessage

1. Confirm sender matches apple_flow_allowed_senders
2. Confirm message uses relay: prefix (or explicit command prefix)
3. Confirm sender allowlist polling is on and non-empty
4. Check logs for ignore reason (ignored_missing_chat_prefix, echo suppression, rate limit)

C) Approval Flow Confusion (task: / project:)

1. Confirm plan is produced first
2. Confirm approval request id issued
3. Confirm only original sender can approve/deny
4. Confirm expiration handling and status transitions are preserved

Acceptance Checklist

Before finishing a apple-flow task, confirm:

• Safety defaults preserved (unless explicitly changed by request)
• Patch is minimal and scoped to root cause
• Config/docs/examples are in sync if config changed
• pytest -q passes
• Final summary includes what changed, why, and how it was verified