From aff194d17efe253c3ed037ad2061bcccd3bc1a5b Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:13:00 +0000 Subject: [PATCH 1/6] docs: plan for cross-harness agent config migration Plan to move agent configuration out of .cursor/ into open formats: rules become a root AGENTS.md (agents.md), skills move to a neutral .skills/ directory per the Agent Skills specification, with committed symlinks so both Claude Code and Cursor discover them. .cursor/plans/ is retained as-is with a deprecation README. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z --- docs/dev_todo/cross_harness_agent_config.md | 121 ++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/dev_todo/cross_harness_agent_config.md diff --git a/docs/dev_todo/cross_harness_agent_config.md b/docs/dev_todo/cross_harness_agent_config.md new file mode 100644 index 00000000..2f2fd4da --- /dev/null +++ b/docs/dev_todo/cross_harness_agent_config.md @@ -0,0 +1,121 @@ +# 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). Link it from `AGENTS.md` and add it to the `docs/README.md` **Build & Development** section. + +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//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 to verify during implementation** — the Unison profile (`~/.unison/non_windows_cnplus.prf`) sets neither `links` nor `follow`, and the repo has zero tracked symlinks today, so this is new ground for the sync setup. After the first sync, confirm the symlinks arrive as symlinks and that Unison did not replace a directory with a link. 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. Do not let a broken sync silently degrade the checkout; the `wsl-unison-setup` doc already records how destructive that failure mode is. + +### 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 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/`. +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 — the one step with real downside if it goes wrong. + +## Open Questions + +None blocking. The Unison symlink behavior in Phase 3 is the only unknown, with a stated fallback. From f2fc2a57add944cfe204687dfe1e9ab9cd9df120 Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:19:23 +0000 Subject: [PATCH 2/6] docs: call out WSL/Unison setup explicitly in AGENTS.md Per PR review: a bare link to the environment doc is too easy to skip. AGENTS.md gets a short Development Environment section naming the dual-filesystem setup, sync delay, and Windows-only instrumentation tests, pointing at the full doc for detail. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z --- docs/dev_todo/cross_harness_agent_config.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/dev_todo/cross_harness_agent_config.md b/docs/dev_todo/cross_harness_agent_config.md index 2f2fd4da..bafb76bf 100644 --- a/docs/dev_todo/cross_harness_agent_config.md +++ b/docs/dev_todo/cross_harness_agent_config.md @@ -45,7 +45,9 @@ Two additions on top of the straight port: `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). Link it from `AGENTS.md` and add it to the `docs/README.md` **Build & Development** section. +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. @@ -90,7 +92,7 @@ Branch, commit, push, and open with `gh pr create` against `master` (`williscool | File | Change | |------|--------| -| `AGENTS.md` | **New** — from `main-rules.mdc`, frontmatter dropped, agent-config + orientation sections added | +| `AGENTS.md` | **New** — from `main-rules.mdc`, frontmatter dropped, agent-config + orientation + **Development Environment** 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/`) | From d93fe5c39ccdb88907674f9f7c1172e08d8b2d71 Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:21:15 +0000 Subject: [PATCH 3/6] refactor: move agent config to cross-harness formats Rules become a root AGENTS.md (agents.md format); skills move to a harness-neutral .skills/ directory per the Agent Skills specification, with committed symlinks so both Claude Code and Cursor discover them. - .cursor/rules/main-rules.mdc -> AGENTS.md (frontmatter dropped, body preserved verbatim; adds Agent Configuration, Development Environment and Planning sections) - .cursor/rules/wsl-unison-setup.mdc -> docs/build/wsl_unison_environment.md (alwaysApply:false reference material belongs in the docs tree) - .cursor/skills/* -> .skills/*, with .claude/skills and .cursor/skills as symlinks - plan-making templates -> assets/ per spec convention - github-pr-comments: close unterminated code fence - .cursor/plans/ retained with a deprecation README Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z --- .claude/skills | 1 + .cursor/plans/README.md | 23 +++++++++++++ .cursor/skills | 1 + .../github-pr-comments/SKILL.md | 1 + .../skills => .skills}/plan-making/SKILL.md | 10 +++--- .../plan-making/assets}/template-large.md | 0 .../plan-making/assets}/template-small.md | 0 .cursor/rules/main-rules.mdc => AGENTS.md | 34 +++++++++++++++---- docs/README.md | 1 + .../build/wsl_unison_environment.md | 3 -- 10 files changed, 61 insertions(+), 13 deletions(-) create mode 120000 .claude/skills create mode 100644 .cursor/plans/README.md create mode 120000 .cursor/skills rename {.cursor/skills => .skills}/github-pr-comments/SKILL.md (99%) rename {.cursor/skills => .skills}/plan-making/SKILL.md (84%) rename {.cursor/skills/plan-making => .skills/plan-making/assets}/template-large.md (100%) rename {.cursor/skills/plan-making => .skills/plan-making/assets}/template-small.md (100%) rename .cursor/rules/main-rules.mdc => AGENTS.md (54%) rename .cursor/rules/wsl-unison-setup.mdc => docs/build/wsl_unison_environment.md (99%) diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000..4ca0ec66 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.skills \ No newline at end of file diff --git a/.cursor/plans/README.md b/.cursor/plans/README.md new file mode 100644 index 00000000..cec3aad9 --- /dev/null +++ b/.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. diff --git a/.cursor/skills b/.cursor/skills new file mode 120000 index 00000000..4ca0ec66 --- /dev/null +++ b/.cursor/skills @@ -0,0 +1 @@ +../.skills \ No newline at end of file diff --git a/.cursor/skills/github-pr-comments/SKILL.md b/.skills/github-pr-comments/SKILL.md similarity index 99% rename from .cursor/skills/github-pr-comments/SKILL.md rename to .skills/github-pr-comments/SKILL.md index c9604525..97d297c8 100644 --- a/.cursor/skills/github-pr-comments/SKILL.md +++ b/.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 +``` diff --git a/.cursor/skills/plan-making/SKILL.md b/.skills/plan-making/SKILL.md similarity index 84% rename from .cursor/skills/plan-making/SKILL.md rename to .skills/plan-making/SKILL.md index 064eb232..ff76fab9 100644 --- a/.cursor/skills/plan-making/SKILL.md +++ b/.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 diff --git a/.cursor/skills/plan-making/template-large.md b/.skills/plan-making/assets/template-large.md similarity index 100% rename from .cursor/skills/plan-making/template-large.md rename to .skills/plan-making/assets/template-large.md diff --git a/.cursor/skills/plan-making/template-small.md b/.skills/plan-making/assets/template-small.md similarity index 100% rename from .cursor/skills/plan-making/template-small.md rename to .skills/plan-making/assets/template-small.md diff --git a/.cursor/rules/main-rules.mdc b/AGENTS.md similarity index 54% rename from .cursor/rules/main-rules.mdc rename to AGENTS.md index 89904660..275c86c4 100644 --- a/.cursor/rules/main-rules.mdc +++ b/AGENTS.md @@ -1,9 +1,25 @@ ---- -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. + +## Agent Configuration + +This repo keeps agent configuration in open, cross-harness formats: + +- **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). + +## Development Environment + +**This project uses a dual-filesystem WSL setup.** Read [docs/build/wsl_unison_environment.md](docs/build/wsl_unison_environment.md) before building or running tests — these constraints will bite you otherwise: + +- **Edits happen on Linux; Android builds happen on Windows.** Source lives at `/home/william/not_connected_to_windows/CalendarNotification` (Linux) and syncs to `C:\dev\CN` (Windows). Build from the Windows short path to avoid the 260-char path limit. +- **Unison syncs every 10 seconds.** Wait ~15s after changing files before running anything on the Windows side — there is no inotify on Windows mounts. +- **Instrumentation tests (`connectedAndroidTest`) must run from Windows**, not WSL. The test runner needs ports that don't work through WSL. +- **Never sync through the junction** at the old long path — doing so can replace the Linux directory with a symlink and destroy data. Details in the doc above. # Code Changes @@ -69,4 +85,10 @@ 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. \ No newline at end of file +See `docs/architecture/clock_implementation.md` and `docs/dev_todo/system_current_time_millis_removal.md` for details. + +# 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. diff --git a/docs/README.md b/docs/README.md index 36213f57..ab1e4bf5 100644 --- a/docs/README.md +++ b/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 diff --git a/.cursor/rules/wsl-unison-setup.mdc b/docs/build/wsl_unison_environment.md similarity index 99% rename from .cursor/rules/wsl-unison-setup.mdc rename to docs/build/wsl_unison_environment.md index bc00e072..d43cf6da 100644 --- a/.cursor/rules/wsl-unison-setup.mdc +++ b/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: From a78359259948f67d4cf52cf546791febd95f92fc Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:27:19 +0000 Subject: [PATCH 4/6] docs: never run unison without explicit permission A misconfigured or mistimed sync can destroy work in ways that are hard to restore and may require a machine restart, so this is a standing rule rather than a judgment call. - AGENTS.md: dedicated section prohibiting agent-initiated unison runs - docs/build/wsl_unison_environment.md: warning at the point of use - plan: Phase 3 round-trip verification is now explicitly user-run only Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01N34fouw76cNkoFVg6V3j4Z --- AGENTS.md | 8 ++++++++ docs/build/wsl_unison_environment.md | 5 +++++ docs/dev_todo/cross_harness_agent_config.md | 10 +++++++--- 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 275c86c4..ff61b047 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,14 @@ This repo keeps agent configuration in open, cross-harness formats: - **Instrumentation tests (`connectedAndroidTest`) must run from Windows**, not WSL. The test runner needs ports that don't work through WSL. - **Never sync through the junction** at the old long path — doing so can replace the Linux directory with a symlink and destroy data. Details in the doc above. +## NEVER run Unison without explicit permission + +**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. + # Code Changes This is a legacy codebase (2016) with a robust test suite added in 2024-25. diff --git a/docs/build/wsl_unison_environment.md b/docs/build/wsl_unison_environment.md index d43cf6da..b8ae4d1d 100644 --- a/docs/build/wsl_unison_environment.md +++ b/docs/build/wsl_unison_environment.md @@ -18,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. diff --git a/docs/dev_todo/cross_harness_agent_config.md b/docs/dev_todo/cross_harness_agent_config.md index bafb76bf..8c1e471e 100644 --- a/docs/dev_todo/cross_harness_agent_config.md +++ b/docs/dev_todo/cross_harness_agent_config.md @@ -78,7 +78,11 @@ Cursor keeps working unchanged; Claude Code gains discovery it didn't have (ther **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 to verify during implementation** — the Unison profile (`~/.unison/non_windows_cnplus.prf`) sets neither `links` nor `follow`, and the repo has zero tracked symlinks today, so this is new ground for the sync setup. After the first sync, confirm the symlinks arrive as symlinks and that Unison did not replace a directory with a link. 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. Do not let a broken sync silently degrade the checkout; the `wsl-unison-setup` doc already records how destructive that failure mode is. +**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/` @@ -92,7 +96,7 @@ Branch, commit, push, and open with `gh pr create` against `master` (`williscool | File | Change | |------|--------| -| `AGENTS.md` | **New** — from `main-rules.mdc`, frontmatter dropped, agent-config + orientation + **Development Environment** sections added | +| `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/`) | @@ -116,7 +120,7 @@ Verification is structural: 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/`. 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 — the one step with real downside if it goes wrong. +6. Unison round-trip per Phase 3 — **user-run only**, never by an agent. ## Open Questions From 2a51a9dcb03d7d2fed519399ad644cb7c95c4a8c Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:47:59 +0000 Subject: [PATCH 5/6] doc: slight tweak --- AGENTS.md | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ff61b047..7b080f40 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,14 +12,9 @@ This repo keeps agent configuration in open, cross-harness formats: - `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). -## Development Environment +# Development Environment -**This project uses a dual-filesystem WSL setup.** Read [docs/build/wsl_unison_environment.md](docs/build/wsl_unison_environment.md) before building or running tests — these constraints will bite you otherwise: - -- **Edits happen on Linux; Android builds happen on Windows.** Source lives at `/home/william/not_connected_to_windows/CalendarNotification` (Linux) and syncs to `C:\dev\CN` (Windows). Build from the Windows short path to avoid the 260-char path limit. -- **Unison syncs every 10 seconds.** Wait ~15s after changing files before running anything on the Windows side — there is no inotify on Windows mounts. -- **Instrumentation tests (`connectedAndroidTest`) must run from Windows**, not WSL. The test runner needs ports that don't work through WSL. -- **Never sync through the junction** at the old long path — doing so can replace the Linux directory with a symlink and destroy data. Details in the doc above. +**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: ## NEVER run Unison without explicit permission @@ -29,6 +24,12 @@ A misconfigured or mistimed sync can destroy work in ways that are hard or impos 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. + # Code Changes This is a legacy codebase (2016) with a robust test suite added in 2024-25. @@ -94,9 +95,3 @@ Use `CNPlusClockInterface` instead - it enables testable time-dependent code. **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. - -# 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. From ee759be8f501b5cb29ecc6d84833675d67915c25 Mon Sep 17 00:00:00 2001 From: William Harris Date: Sun, 20 Sep 2026 19:54:18 +0000 Subject: [PATCH 6/6] docs: rule ordering update --- AGENTS.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b080f40..97427028 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,16 @@ Use the `plan-making` skill in `.skills/plan-making/` when a task warrants a wri **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 + +Always think of the minimum viable solution to a problem or change to make. make sure that works and then build on top of it. break things down into small testable pieces first. That said + +**NO CHEATING!** I.e. don't comment out or skip a test to solve a problem unless its just a temporary bandaid while working on something more important. + +# keep all code implementations as consise as possible. + +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. @@ -48,18 +58,6 @@ When in doubt, add tests first. 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 - -# Don't try to boil the ocean. Dont try to make big sweeping changes when more focused ones will do - -Always think of the minimum viable solution to a problem or change to make. make sure that works and then build on top of it. break things down into small testable pieces first. That said - -**NO CHEATING!** I.e. don't comment out or skip a test to solve a problem unless its just a temporary bandaid while working on something more important. - -# keep all code implementations as consise as possible. - -Everything it needs nothing it doesn't. Every new line of code is one that potentially doesn't work 😄 - - # Check documentation if implementing something potentially complex or nonstandard. See `docs/README.md` for the full documentation index. often there are things we've learned already i.e.