refactor: move agent config to cross-harness formats (AGENTS.md + .skills/)

.claude/skills

@@ -0,0 +1 @@
+../.skills

.cursor/plans/README.md

@@ -0,0 +1,23 @@
+# Deprecated: Cursor Plan Mode Output
+
+**This directory is deprecated and kept for historical reference only.**
+
+The `*.plan.md` files here were produced by Cursor's built-in Plan Mode. That
+format is proprietary and throwaway-oriented — it was never intended as
+long-lived documentation, and it is not used in this project going forward.
+
+The files are retained because they capture real historical context about past
+work. They are **not** current practice, and nothing here should be treated as
+an active plan or an up-to-date description of the codebase.
+
+## Current practice
+
+Development plans are learning artifacts kept in the docs tree:
+
+- **`docs/dev_todo/`** — active plans
+- **`docs/dev_completed/`** — finished work, indexed in `docs/README.md`
+
+Use the [`plan-making` skill](../../.skills/plan-making/SKILL.md) to write new
+plans. It picks a size-appropriate template and enforces the repo conventions.
+
+Do not add new files to this directory.

.cursor/skills

@@ -0,0 +1 @@
+../.skills

.cursor/skills/github-pr-comments/SKILL.md → .skills/github-pr-comments/SKILL.md

@@ -58,3 +58,4 @@ gh api graphql -f query='
     }
   }
 ' -f owner=OWNER -f repo=REPO -F prNumber=PR_NUMBER
+```

.cursor/skills/plan-making/SKILL.md → .skills/plan-making/SKILL.md

@@ -5,9 +5,11 @@ description: Creates development plan documents in docs/dev_todo/ using size-app
 
 # Plan Making
 
-## CRITICAL: Never Use Cursor Plan Mode
+## CRITICAL: Never Use Editor Plan Mode
 
-**Do NOT use Cursor's built-in Plan Mode or create `.cursor/plans/*.plan.md` files.** That format is proprietary, throwaway-oriented, and not suitable for long-lived documentation. Plans in this project are learning artifacts kept in `docs/dev_todo/` (active) and `docs/dev_completed/` (done).
+**Do NOT use an editor's built-in Plan Mode (e.g. Cursor's) or create `.cursor/plans/*.plan.md` files.** Those formats are proprietary, throwaway-oriented, and not suitable for long-lived documentation. Plans in this project are learning artifacts kept in `docs/dev_todo/` (active) and `docs/dev_completed/` (done).
+
+The `.cursor/plans/` directory is retained for historical reference only and is deprecated — see its `README.md`.
 
 ## Workflow
 
@@ -36,8 +38,8 @@ Pick the size that matches the majority of signals. When borderline, size down 
 
 ### Step 3: Select Template
 
-- **S or M** → Read [template-small.md](template-small.md) and follow it
-- **L or XL** → Read [template-large.md](template-large.md) and follow it
+- **S or M** → Read [template-small.md](assets/template-small.md) and follow it
+- **L or XL** → Read [template-large.md](assets/template-large.md) and follow it
 
 ### Step 4: Write the Plan
 

.cursor/rules/main-rules.mdc → AGENTS.md

@@ -1,28 +1,34 @@
----
-description: 
-globs: 
-alwaysApply: true
----
+# Calendar Notifications Plus — Agent Guide
 
+Android calendar notification app (Kotlin) with a React Native / Expo layer. Originally written in 2016; a robust test suite was added in 2024-25.
 
-# Code Changes
+## Agent Configuration
 
-This is a legacy codebase (2016) with a robust test suite added in 2024-25.
+This repo keeps agent configuration in open, cross-harness formats:
 
-**Permitted without confirmation:**
-- Bug fixes with corresponding test coverage
-- Refactoring with existing test coverage
-- Removal of deprecated features (QuietHours, CalendarEditor)
+- **This file** (`AGENTS.md`) — project rules, always applicable. See [agents.md](https://agents.md/).
+- **`.skills/`** — reusable skills following the [Agent Skills specification](https://agentskills.io/specification). Symlinked as `.claude/skills` and `.cursor/skills` so both harnesses discover them.
+  - `plan-making` — writing development plans into `docs/dev_todo/`
+  - `github-pr-comments` — fetching PR review threads with line numbers and resolution status
+- **`docs/`** — architecture, build, and testing documentation. Start at [docs/README.md](docs/README.md).
 
-**Requires tests first:**
-- New features or significant changes
+# Development Environment
 
-When in doubt, add tests first.
+**This project's core maintainer uses a dual-filesystem WSL setup.** Read [docs/build/wsl_unison_environment.md](docs/build/wsl_unison_environment.md) before building or running tests — take care of these constraints when working on Windows or WSL:
 
-# Work to make tests as faithful to the real code as possible
+## NEVER run Unison without explicit permission
 
-its ok to mock out core android apis that the instrumentation testsuite doesn't work well with i.e. making push notifications but try to use the real original code for anything that exists in this codebase
+**Do not run `unison` — in any form, for any reason — unless the user has explicitly asked for it in the current request.** This includes "just syncing to check something" or verifying that a change propagated.
+
+A misconfigured or mistimed sync can destroy work in ways that are hard or impossible to restore, and recovering may require restarting the machine. The blast radius is the entire checkout on both sides.
 
+If you believe a sync is needed, **stop and ask.** Say what you want to sync and why, then wait. The user runs it, or tells you to.
+
+# Planning
+
+Use the `plan-making` skill in `.skills/plan-making/` when a task warrants a written plan. Plans live in `docs/dev_todo/` (active) and move to `docs/dev_completed/` when done.
+
+**Do not use an editor's built-in Plan Mode** or create `.cursor/plans/*.plan.md` files — that directory is deprecated and retained for historical reference only.
 
 # Don't try to boil the ocean. Dont try to make big sweeping changes when more focused ones will do
 
@@ -34,6 +40,23 @@ Always think of the minimum viable solution to a problem or change to make. make
 
 Everything it needs nothing it doesn't. Every new line of code is one that potentially doesn't work 😄
 
+# Code Changes
+
+This is a legacy codebase (2016) with a robust test suite added in 2024-25.
+
+**Permitted without confirmation:**
+- Bug fixes with corresponding test coverage
+- Refactoring with existing test coverage
+- Removal of deprecated features (QuietHours, CalendarEditor)
+
+**Requires tests first:**
+- New features or significant changes
+
+When in doubt, add tests first.
+
+# Work to make tests as faithful to the real code as possible
+
+its ok to mock out core android apis that the instrumentation testsuite doesn't work well with i.e. making push notifications but try to use the real original code for anything that exists in this codebase
 
 # Check documentation if implementing something potentially complex or nonstandard.
 
@@ -69,4 +92,4 @@ Use `CNPlusClockInterface` instead - it enables testable time-dependent code.
 **Production code:** Inject `CNPlusSystemClock()` or access via interface property
 **Test code:** Use `TestTimeConstants.STANDARD_TEST_TIME` or `CNPlusTestClock`
 
-See `docs/architecture/clock_implementation.md` and `docs/dev_todo/system_current_time_millis_removal.md` for details.
+See `docs/architecture/clock_implementation.md` and `docs/dev_todo/system_current_time_millis_removal.md` for details.

docs/README.md

@@ -16,6 +16,7 @@
 - [CR-SQLite Build](build/CR_SQLITE_BUILD.md) - Building cr-sqlite native library
 - [Debug Guide](build/DEBUG.md) - Debugging tips (Chrome/Hermes limitations)
 - [WSL Log Cleaning](build/wsl_test_log_clean.md) - Log cleaning scripts for sharing
+- [WSL/Unison Environment](build/wsl_unison_environment.md) - Dual-filesystem dev setup, sync, Windows-only instrumentation tests
 
 ## Data & Sync
 

.cursor/rules/wsl-unison-setup.mdc → docs/build/wsl_unison_environment.md

@@ -1,6 +1,3 @@
----
-alwaysApply: false
----
 # Development Environment Setup - WSL/Unison Sync
 
 This project uses a dual-filesystem setup for development:
@@ -21,6 +18,11 @@ This project uses a dual-filesystem setup for development:
 - **`node_modules` is NOT synced** — install separately on each side
 - Run with: `unison non_windows_cnplus`
 
+> **⚠️ Agents: never run `unison` without explicit permission from the user.**
+> A misconfigured or mistimed sync can destroy work in ways that are hard or
+> impossible to restore, and recovery may require a machine restart. If you
+> think a sync is needed, stop and ask — do not run it yourself.
+
 ### ⚠️ CRITICAL: Never sync through the junction!
 
 Unison must point to the **real short path** (`/mnt/c/dev/CN`), NOT the junction path. If you sync through the junction, Unison will replace your Linux directory with a symlink to `/mnt/c/...`, completely defeating the fast-filesystem setup and potentially destroying data.

docs/dev_todo/cross_harness_agent_config.md

@@ -0,0 +1,127 @@
+# Refactor: Cross-Harness Agent Configuration
+
+## Overview
+
+Move the agent configuration out of `.cursor/` into open, cross-harness formats: rules become a root `AGENTS.md` ([agents.md](https://agents.md/)), and skills move to a harness-neutral `.skills/` directory following the [Agent Skills specification](https://agentskills.io/specification). Nothing about this config is Cursor-specific — it's project knowledge that any coding agent should be able to read.
+
+## Background
+
+All agent config currently lives under `.cursor/`, which ties it to one editor:
+
+| Path | Contents | Problem |
+|------|----------|---------|
+| `.cursor/rules/main-rules.mdc` | Project coding rules (`alwaysApply: true`) | `.mdc` + frontmatter is a Cursor format; other agents ignore it |
+| `.cursor/rules/wsl-unison-setup.mdc` | WSL/Unison/Windows build environment (`alwaysApply: false`) | Same, plus it's reference material rather than an always-on rule |
+| `.cursor/skills/plan-making/` | Plan-making skill + 2 templates | Already spec-shaped; just in a vendor folder |
+| `.cursor/skills/github-pr-comments/` | PR review comment fetching | Same |
+| `.cursor/plans/*.plan.md` (6 files) | Cursor Plan Mode output | Proprietary throwaway format |
+
+The irony worth noting: `plan-making/SKILL.md` itself says *"Do NOT use Cursor's built-in Plan Mode or create `.cursor/plans/*.plan.md` files"* — yet six of them are committed. They stay put (see Phase 4), but get labeled so no one mistakes them for current practice.
+
+Skill discovery is the one genuinely unstandardized piece. The Agent Skills spec defines the *format* of a skill, not the *directory* agents scan. Claude Code reads `.claude/skills/`; Cursor reads `.cursor/skills/`. A bare `.skills/` is neutral but auto-discovered by nothing. Hence: canonical content in `.skills/`, with committed symlinks so both harnesses find it.
+
+## Plan
+
+### Phase 1: `AGENTS.md` at repo root
+
+Convert `.cursor/rules/main-rules.mdc` → `AGENTS.md`, dropping the Cursor frontmatter (`description`/`globs`/`alwaysApply`). The spec requires no fields and prescribes no headings, so the body carries over nearly verbatim.
+
+Content is preserved as-is — these are hard-won rules, not up for rewriting in a move:
+- Code-change permission tiers (legacy 2016 codebase, tests-first)
+- Test faithfulness / no-cheating
+- Minimum viable solution, concise implementations
+- Copyright header (William, inherited from Sergey Parshin 2020)
+- Never catch broad `Exception`
+- Never use `System.currentTimeMillis()` — use `CNPlusClockInterface`
+- Key doc references
+
+Two additions on top of the straight port:
+- A short **Agent Configuration** section pointing at `.skills/` and the environment doc, so an agent landing in the repo can find everything from the root file.
+- A brief project/build orientation line, since `AGENTS.md` is the first thing an unfamiliar agent reads.
+
+`.mdc` frontmatter is NOT carried into `AGENTS.md`. `alwaysApply: true` is implicit — the root file always applies.
+
+### Phase 2: WSL/Unison rule → `docs/build/`
+
+`wsl-unison-setup.mdc` is `alwaysApply: false` — reference material, not a standing rule. It belongs in the docs tree, not `AGENTS.md`.
+
+Move to `docs/build/wsl_unison_environment.md`, drop frontmatter, keep content intact (short path `C:\dev\CN`, the never-sync-through-the-junction warning, NativeWind pre-bundle workaround, instrumentation-tests-from-Windows instructions). Add it to the `docs/README.md` **Build & Development** section.
+
+**`AGENTS.md` must call this out explicitly, not just link it.** A bare link is too easy to skip past, and the consequences of not knowing about this setup are real: builds run from a different filesystem than edits, instrumentation tests only work from Windows, and there's a sync path that can destroy the Linux checkout if used wrong. `AGENTS.md` gets a short **Development Environment** section naming the dual-filesystem setup, the ~15s sync delay after edits, and the Windows-only instrumentation-test constraint — each in a line or two, pointing at the full doc for detail. Enough that an agent knows the constraint exists before it trips over it.
+
+This one is genuinely machine-specific (it hardcodes `/home/william/...`), but it's already committed and other agents benefit from it, so it moves rather than being dropped.
+
+### Phase 3: Skills → `.skills/` + harness symlinks
+
+Move both skills to `.skills/<name>/SKILL.md`. Frontmatter (`name`, `description`) already satisfies the spec — `name` matches the parent directory, lowercase-hyphenated, and descriptions state both what and when.
+
+Two spec-conformance fixes while moving:
+- **`plan-making`**: relocate `template-small.md` / `template-large.md` into `assets/`, per the spec's convention for templates. Update the two links in `SKILL.md` to `assets/…` (still one level deep, as recommended).
+- **`github-pr-comments`**: the GraphQL block is an unterminated code fence — the file ends mid-block with no closing ```. Close it.
+
+Also update the self-referential line in `plan-making/SKILL.md` that points at `.cursor/plans/` so it reflects the new deprecation notice.
+
+Then make both harnesses discover them:
+
+```
+.skills/                      # canonical, vendor-neutral
+├── plan-making/
+│   ├── SKILL.md
+│   └── assets/{template-small,template-large}.md
+└── github-pr-comments/SKILL.md
+
+.claude/skills  -> ../.skills  # symlink (committed, mode 120000)
+.cursor/skills  -> ../.skills  # symlink (committed) — replaces the real dir
+```
+
+Cursor keeps working unchanged; Claude Code gains discovery it didn't have (there is no `.claude/` directory in the repo today).
+
+**Verified before committing to this approach:** git stores symlinks as mode `120000` and they round-trip; symlinks create and resolve correctly on the `/mnt/c/dev/CN` DrvFs mount.
+
+**Still open — Unison round-trip.** The profile (`~/.unison/non_windows_cnplus.prf`) sets neither `links` nor `follow`, and the repo had zero tracked symlinks before this change, so this is new ground for the sync setup. Propagating it requires Unison to delete `.cursor/skills` as a directory and recreate it as a symlink.
+
+**This must be done by the user, not by an agent.** Agents must never run `unison` — see the rule in `AGENTS.md`. When the user next syncs, the things to confirm are that `.claude/skills` and `.cursor/skills` arrive as symlinks (not copied directories or broken files), and that no real directory was replaced by a link to itself.
+
+If Unison mishandles them, the fallback is `.skills/` as the sole location with `AGENTS.md` pointing agents at it explicitly (no symlinks) — a real tradeoff, since it costs auto-discovery. Everything else in this migration is independent of that outcome.
+
+### Phase 4: Deprecate `.cursor/plans/`
+
+Leave all six `.plan.md` files in place — git history and their content stay intact. Add `.cursor/plans/README.md` marking the directory deprecated: explain the files are Cursor Plan Mode output kept only for historical reference, that the format is not used going forward, and point to `docs/dev_todo/` + the `plan-making` skill as current practice.
+
+### Phase 5: Open the PR
+
+Branch, commit, push, and open with `gh pr create` against `master` (`williscool/CalendarNotification`).
+
+## Files Changed Summary
+
+| File | Change |
+|------|--------|
+| `AGENTS.md` | **New** — from `main-rules.mdc`, frontmatter dropped, agent-config + orientation + **Development Environment** + **never-run-Unison** sections added |
+| `.cursor/rules/main-rules.mdc` | Deleted (content → `AGENTS.md`) |
+| `docs/build/wsl_unison_environment.md` | **New** — from `wsl-unison-setup.mdc`, frontmatter dropped |
+| `.cursor/rules/wsl-unison-setup.mdc` | Deleted (content → `docs/build/`) |
+| `.cursor/rules/` | Removed (now empty) |
+| `.skills/plan-making/SKILL.md` | Moved; template links → `assets/`, `.cursor/plans` reference updated |
+| `.skills/plan-making/assets/template-{small,large}.md` | Moved into `assets/` per spec |
+| `.skills/github-pr-comments/SKILL.md` | Moved; unterminated code fence closed |
+| `.cursor/skills/` | Directory replaced by symlink → `../.skills` |
+| `.claude/skills` | **New** symlink → `../.skills` |
+| `.cursor/plans/README.md` | **New** — deprecation notice; the 6 `.plan.md` files untouched |
+| `docs/README.md` | Add WSL environment doc to Build & Development |
+
+## Testing
+
+No application code changes — nothing to run against the Android/Jest suites, and no CI impact (no workflow references `.cursor/`; the only in-repo mention is the one line inside `plan-making/SKILL.md`).
+
+Verification is structural:
+
+1. `git ls-files -s .claude .cursor` shows both symlinks as mode `120000`.
+2. Fresh-clone check: symlinks resolve and `SKILL.md` is readable through both `.claude/skills/` and `.cursor/skills/`.
+3. Frontmatter validates against the spec — `name` matches its directory, lowercase/hyphen-only, `description` non-empty and under 1024 chars. Optionally `skills-ref validate ./.skills/<name>`.
+4. Every relative link resolves from its new location: `assets/` template links, `docs/` references in `AGENTS.md`, the new `docs/README.md` entry.
+5. Grep for stale `.cursor/rules` or `.cursor/skills` paths.
+6. Unison round-trip per Phase 3 — **user-run only**, never by an agent.
+
+## Open Questions
+
+None blocking. The Unison symlink behavior in Phase 3 is the only unknown, with a stated fallback.