From bf88617d155d33b572145e28fa4a8b6cf9da7659 Mon Sep 17 00:00:00 2001 From: Brendan Chen Date: Sun, 14 Jun 2026 22:25:42 -0400 Subject: [PATCH 1/2] docs: rename docs/ to Docs/ and make it read-only for agents Rename the documentation directory docs/ -> Docs/ to match the project's capitalized top-level layout (OpenAppLock/, Shared/, Config/), and update every reference in AGENTS.md, CLAUDE.md, CONTRIBUTING.md, and README.md. Add a Documentation rule to AGENTS.md: Docs/ is human-authored reference material that agents read for context but must never create or modify. The goal is for all documentation to be human-written; only AGENTS.md and CLAUDE.md are agent-maintained. Reframe the TDD guidance so agents consult the feature spec rather than editing it, and flag needed spec changes to the maintainer instead. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 31 ++++++++++++++++++++-------- CLAUDE.md | 2 +- CONTRIBUTING.md | 4 ++-- {docs => Docs}/RULES_FEATURE_SPEC.md | 0 {docs => Docs}/SWIFT_GUIDELINES.md | 0 README.md | 4 ++-- 6 files changed, 27 insertions(+), 14 deletions(-) rename {docs => Docs}/RULES_FEATURE_SPEC.md (100%) rename {docs => Docs}/SWIFT_GUIDELINES.md (100%) diff --git a/AGENTS.md b/AGENTS.md index ef09971..cd496da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ OpenAppLock/ App target (iOS 26, SwiftUI + SwiftData) RuleScheduler (rules → DeviceActivity monitoring), AppListMigration, LaunchConfiguration + SampleRules (UI-test harness) - Views/ Native SwiftUI screens (see docs spec §6) + Views/ Native SwiftUI screens (see Docs spec §6) Shared/ Compiled into the app AND all three extensions: RuleKind, Weekday, RuleSchedule, AppGroup, UsageLedger (per-day minutes/opens), @@ -39,13 +39,25 @@ OpenAppLockShieldAction/ ShieldAction extension: Open press spends an open, OpenAppLockTests/ Swift Testing unit suites (@MainActor — the app target defaults to MainActor isolation) OpenAppLockUITests/ XCUITest flows (see harness below) -docs/RULES_FEATURE_SPEC.md Feature spec for the rules behavior; §6 maps it - to the native presentation. Review/update this - BEFORE behavior changes. -docs/SWIFT_GUIDELINES.md Swift coding/testing/patterns/security standards +Docs/RULES_FEATURE_SPEC.md Feature spec for the rules behavior; §6 maps it + to the native presentation. Review this BEFORE + behavior changes (read-only — see Documentation). +Docs/SWIFT_GUIDELINES.md Swift coding/testing/patterns/security standards agents must follow on this project. ``` +## Documentation + +The `Docs/` directory (`RULES_FEATURE_SPEC.md`, `SWIFT_GUIDELINES.md`) is +**human-authored reference material**. Agents may — and should — read it for +context and treat the feature spec as the source of truth, but must **never +create or modify any file under `Docs/`**. The goal is for all documentation to +be written by humans; the only docs an agent maintains are this `AGENTS.md` and +`CLAUDE.md`. + +If a behavior change would make the spec inaccurate, do **not** edit `Docs/` +yourself — flag the needed change so the maintainer can update it. + ## Domain facts worth knowing - Times are stored as **minutes from midnight**; `end <= start` means the @@ -85,10 +97,11 @@ when reminded: - **Always plan before execution.** Think through and lay out the approach (a written plan / plan mode for anything non-trivial) and confirm scope before editing code. Do not start changing files until the plan is clear. -- **Always use red-green TDD.** Update `docs/RULES_FEATURE_SPEC.md` first for - behavior changes, write the failing test, run it (compile failure counts as - red), implement, re-run focused tests, then the full suite. Run tests often - and fail fast. +- **Always use red-green TDD.** Consult `Docs/RULES_FEATURE_SPEC.md` first for + behavior changes — it is the source of truth, but it is human-authored, so + read it rather than editing it (see Documentation above). Then write the + failing test, run it (compile failure counts as red), implement, re-run + focused tests, then the full suite. Run tests often and fail fast. - **Always attempt to validate the UI manually before committing.** Build and run the app (simulator/device) and visually confirm the change behaves as intended. This step **may be skipped only when such tooling is unavailable** diff --git a/CLAUDE.md b/CLAUDE.md index efa9431..4cd7c87 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,4 +2,4 @@ All project context for agents lives in [AGENTS.md](AGENTS.md) — read that first. Feature behavior is specified in -[docs/RULES_FEATURE_SPEC.md](docs/RULES_FEATURE_SPEC.md). +[Docs/RULES_FEATURE_SPEC.md](Docs/RULES_FEATURE_SPEC.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f64f141..6f7926c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,9 +72,9 @@ xcodebuild test \ ``` Follow red-green TDD: for any behavior change, update -[`docs/RULES_FEATURE_SPEC.md`](docs/RULES_FEATURE_SPEC.md) first, write the +[`Docs/RULES_FEATURE_SPEC.md`](Docs/RULES_FEATURE_SPEC.md) first, write the failing test, then implement. See [`AGENTS.md`](AGENTS.md) and -`docs/SWIFT_GUIDELINES.md` for the project's coding and testing standards. +`Docs/SWIFT_GUIDELINES.md` for the project's coding and testing standards. ## Branch & PR workflow diff --git a/docs/RULES_FEATURE_SPEC.md b/Docs/RULES_FEATURE_SPEC.md similarity index 100% rename from docs/RULES_FEATURE_SPEC.md rename to Docs/RULES_FEATURE_SPEC.md diff --git a/docs/SWIFT_GUIDELINES.md b/Docs/SWIFT_GUIDELINES.md similarity index 100% rename from docs/SWIFT_GUIDELINES.md rename to Docs/SWIFT_GUIDELINES.md diff --git a/README.md b/README.md index 64debe6..3c2d661 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,10 @@ identifier steps in [CONTRIBUTING.md](CONTRIBUTING.md). | `OpenAppLockShieldConfig/` | ShieldConfiguration extension (shield UI) | | `OpenAppLockShieldAction/` | ShieldAction extension (Open button handling) | | `Config/` | Build configuration (`.xcconfig`) — see CONTRIBUTING.md | -| `docs/` | Feature spec and Swift guidelines | +| `Docs/` | Feature spec and Swift guidelines | Deeper architecture notes live in [AGENTS.md](AGENTS.md); feature behavior is -specified in [docs/RULES_FEATURE_SPEC.md](docs/RULES_FEATURE_SPEC.md). +specified in [Docs/RULES_FEATURE_SPEC.md](Docs/RULES_FEATURE_SPEC.md). ## Contributing From 8c1d0e0286cdb5209516afde7cdfe8c5a0cda5b0 Mon Sep 17 00:00:00 2001 From: Brendan Chen Date: Sun, 14 Jun 2026 22:47:30 -0400 Subject: [PATCH 2/2] docs: mark agent-managed docs with AGENT_ prefix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename Docs/RULES_FEATURE_SPEC.md and Docs/SWIFT_GUIDELINES.md to AGENT_-prefixed names and switch the documentation policy from directory-based (everything under Docs/ is read-only) to filename-based: - AGENT_-prefixed files (plus AGENTS.md, CLAUDE.md) are agent-managed — agents may read, create, and edit them and keep them current. - All other docs (README.md, CONTRIBUTING.md, future human-authored docs) remain read-only to agents. The prefix is the contract, so newly added human docs are off-limits by default. Updates all cross-references in AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README.md, and the spec link inside the guidelines file. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 46 +++++++++++-------- CLAUDE.md | 2 +- CONTRIBUTING.md | 6 +-- ...RE_SPEC.md => AGENT_RULES_FEATURE_SPEC.md} | 0 ...UIDELINES.md => AGENT_SWIFT_GUIDELINES.md} | 2 +- README.md | 2 +- 6 files changed, 34 insertions(+), 24 deletions(-) rename Docs/{RULES_FEATURE_SPEC.md => AGENT_RULES_FEATURE_SPEC.md} (100%) rename Docs/{SWIFT_GUIDELINES.md => AGENT_SWIFT_GUIDELINES.md} (98%) diff --git a/AGENTS.md b/AGENTS.md index cd496da..cc72984 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,24 +39,33 @@ OpenAppLockShieldAction/ ShieldAction extension: Open press spends an open, OpenAppLockTests/ Swift Testing unit suites (@MainActor — the app target defaults to MainActor isolation) OpenAppLockUITests/ XCUITest flows (see harness below) -Docs/RULES_FEATURE_SPEC.md Feature spec for the rules behavior; §6 maps it - to the native presentation. Review this BEFORE - behavior changes (read-only — see Documentation). -Docs/SWIFT_GUIDELINES.md Swift coding/testing/patterns/security standards - agents must follow on this project. +Docs/AGENT_RULES_FEATURE_SPEC.md + Feature spec for the rules behavior; §6 maps it to + the native presentation. Source of truth — review + BEFORE behavior changes, keep current after them + (agent-managed; see Documentation). +Docs/AGENT_SWIFT_GUIDELINES.md + Swift coding/testing/patterns/security standards + agents must follow on this project (agent-managed). ``` ## Documentation -The `Docs/` directory (`RULES_FEATURE_SPEC.md`, `SWIFT_GUIDELINES.md`) is -**human-authored reference material**. Agents may — and should — read it for -context and treat the feature spec as the source of truth, but must **never -create or modify any file under `Docs/`**. The goal is for all documentation to -be written by humans; the only docs an agent maintains are this `AGENTS.md` and -`CLAUDE.md`. +Documentation splits into two buckets, distinguished by **filename**, not by +directory: -If a behavior change would make the spec inaccurate, do **not** edit `Docs/` -yourself — flag the needed change so the maintainer can update it. +- **Agent-managed** — this `AGENTS.md`, `CLAUDE.md`, and any file whose name is + prefixed with `AGENT_` (currently `Docs/AGENT_RULES_FEATURE_SPEC.md` and + `Docs/AGENT_SWIFT_GUIDELINES.md`). Agents may **read, create, and edit** these + and are expected to keep them accurate. Treat the feature spec as the source + of truth for behavior, and update it when a behavior change makes it stale. +- **Human-authored** — every other doc, e.g. `README.md` and `CONTRIBUTING.md`. + Agents may **read** these for context but must **never create or modify** + them; flag needed changes for the maintainer instead. + +The `AGENT_` prefix is the contract: it marks a file as safe for agents to +maintain. Any human-authored doc added without the prefix is automatically +off-limits to agent edits. ## Domain facts worth knowing @@ -97,11 +106,12 @@ when reminded: - **Always plan before execution.** Think through and lay out the approach (a written plan / plan mode for anything non-trivial) and confirm scope before editing code. Do not start changing files until the plan is clear. -- **Always use red-green TDD.** Consult `Docs/RULES_FEATURE_SPEC.md` first for - behavior changes — it is the source of truth, but it is human-authored, so - read it rather than editing it (see Documentation above). Then write the - failing test, run it (compile failure counts as red), implement, re-run - focused tests, then the full suite. Run tests often and fail fast. +- **Always use red-green TDD.** Consult `Docs/AGENT_RULES_FEATURE_SPEC.md` + first for behavior changes — it is the source of truth. If a behavior change + makes the spec inaccurate, keep it current (it is agent-managed; see + Documentation above). Then write the failing test, run it (compile failure + counts as red), implement, re-run focused tests, then the full suite. Run + tests often and fail fast. - **Always attempt to validate the UI manually before committing.** Build and run the app (simulator/device) and visually confirm the change behaves as intended. This step **may be skipped only when such tooling is unavailable** diff --git a/CLAUDE.md b/CLAUDE.md index 4cd7c87..4b7687b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,4 +2,4 @@ All project context for agents lives in [AGENTS.md](AGENTS.md) — read that first. Feature behavior is specified in -[Docs/RULES_FEATURE_SPEC.md](Docs/RULES_FEATURE_SPEC.md). +[Docs/AGENT_RULES_FEATURE_SPEC.md](Docs/AGENT_RULES_FEATURE_SPEC.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f7926c..134bb14 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,9 +72,9 @@ xcodebuild test \ ``` Follow red-green TDD: for any behavior change, update -[`Docs/RULES_FEATURE_SPEC.md`](Docs/RULES_FEATURE_SPEC.md) first, write the -failing test, then implement. See [`AGENTS.md`](AGENTS.md) and -`Docs/SWIFT_GUIDELINES.md` for the project's coding and testing standards. +[`Docs/AGENT_RULES_FEATURE_SPEC.md`](Docs/AGENT_RULES_FEATURE_SPEC.md) first, +write the failing test, then implement. See [`AGENTS.md`](AGENTS.md) and +`Docs/AGENT_SWIFT_GUIDELINES.md` for the project's coding and testing standards. ## Branch & PR workflow diff --git a/Docs/RULES_FEATURE_SPEC.md b/Docs/AGENT_RULES_FEATURE_SPEC.md similarity index 100% rename from Docs/RULES_FEATURE_SPEC.md rename to Docs/AGENT_RULES_FEATURE_SPEC.md diff --git a/Docs/SWIFT_GUIDELINES.md b/Docs/AGENT_SWIFT_GUIDELINES.md similarity index 98% rename from Docs/SWIFT_GUIDELINES.md rename to Docs/AGENT_SWIFT_GUIDELINES.md index a28aa22..cb5b1b2 100644 --- a/Docs/SWIFT_GUIDELINES.md +++ b/Docs/AGENT_SWIFT_GUIDELINES.md @@ -118,7 +118,7 @@ swift test --enable-code-coverage ### Workflow -Red-green TDD: update `docs/RULES_FEATURE_SPEC.md` first for behavior changes, +Red-green TDD: update `Docs/AGENT_RULES_FEATURE_SPEC.md` first for behavior changes, write the failing test, run it (a compile failure counts as red), implement, re-run focused tests, then the full suite. Run tests often and fail fast. diff --git a/README.md b/README.md index 3c2d661..d9c1679 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ identifier steps in [CONTRIBUTING.md](CONTRIBUTING.md). | `Docs/` | Feature spec and Swift guidelines | Deeper architecture notes live in [AGENTS.md](AGENTS.md); feature behavior is -specified in [Docs/RULES_FEATURE_SPEC.md](Docs/RULES_FEATURE_SPEC.md). +specified in [Docs/AGENT_RULES_FEATURE_SPEC.md](Docs/AGENT_RULES_FEATURE_SPEC.md). ## Contributing