Skip to content

Commit cd6ae1c

Browse files
LPFchanLPFchan
committed
Adopt repo-template workflow and commit provenance
Add repo-template operating surfaces, local writing guides, and commit provenance enforcement through tracked hooks and CI. project: aware agent: 019d6ebe-3413-78d3-bdae-c7af38845b64 role: orchestrator artifacts: DEC-20260409-001, LOG-20260409-001, DEC-20260409-002, LOG-20260409-002, DEC-20260409-003, LOG-20260409-003
1 parent 38f3713 commit cd6ae1c

24 files changed

Lines changed: 1400 additions & 66 deletions

‎.githooks/commit-msg‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/sh
2+
3+
set -eu
4+
5+
repo_root=$(git rev-parse --show-toplevel)
6+
exec "$repo_root/scripts/check-commit-standards.sh" "$1"

‎.github/workflows/commit-standards.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Commit Standards
2+
3+
on:
4+
pull_request:
5+
branches: [main, master]
6+
push:
7+
branches: [main, master]
8+
9+
jobs:
10+
commit-standards:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Check out repository
14+
uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- name: Make scripts executable
19+
run: chmod +x .githooks/commit-msg scripts/check-commit-standards.sh scripts/check-commit-range.sh scripts/install-hooks.sh
20+
21+
- name: Validate pull request commits
22+
if: github.event_name == 'pull_request'
23+
run: scripts/check-commit-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}"
24+
25+
- name: Validate pushed commits
26+
if: github.event_name == 'push'
27+
run: scripts/check-commit-range.sh "${{ github.event.before }}" "${{ github.sha }}"

‎AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Agent Instructions
2+
3+
This repo uses repo-template.
4+
5+
Treat `AGENTS.md` as a compatibility entrypoint for tools that look for repo-level agent instructions. The canonical rules live in `repo-operating-model.md`.
6+
7+
## Read First
8+
9+
- `repo-operating-model.md`
10+
- `SPEC.md`
11+
- `STATUS.md`
12+
- `PLANS.md`
13+
- `INBOX.md`
14+
15+
If the repo includes reusable workflows, also read `skills/README.md` and the relevant `skills/<name>/SKILL.md`.
16+
17+
When writing into a repo surface or artifact directory, read the matching local guide first. That means the surface template itself for `SPEC.md`, `STATUS.md`, `PLANS.md`, and `INBOX.md`, and the local `README.md` in directories such as `research/`, `records/decisions/`, and `records/agent-worklogs/`.
18+
19+
## Repo-Specific Notes
20+
21+
- Build verification: `xcodebuild -scheme Aware -configuration Debug -derivedDataPath build build`
22+
- Commit provenance setup: `scripts/install-hooks.sh` configures the tracked `commit-msg` hook locally.
23+
- Commit provenance checks: `scripts/check-commit-standards.sh <commit-message-file>` and `scripts/check-commit-range.sh <base> <head>`
24+
- There is no dedicated automated test suite in the repo today. For runtime changes, use the build plus focused manual validation.
25+
- Preserve the product and workflow constraints in `SPEC.md`: menu bar-only UX, local presence detection, no telemetry or analytics, and safe failure when camera access is denied or unavailable.
26+
- `AWARE-AGENT-PROMPT.md` is a legacy bootstrap helper. Do not treat it as a second policy layer.
27+
28+
## Operating Rules
29+
30+
- Keep durable truth in repo files, not only in chat.
31+
- Route work using the routing ladder in `repo-operating-model.md`.
32+
- Preserve the boundary between `SPEC.md`, `STATUS.md`, `PLANS.md`, `INBOX.md`, `research/`, `records/decisions/`, and `records/agent-worklogs/`.
33+
- Worker agents should prefer worklogs, evidence, and proposals. The orchestrator or operator owns truth-doc updates unless the operator explicitly allows a different flow.
34+
- When creating artifacts or commits, follow the stable-ID and provenance rules in `repo-operating-model.md`.
35+
- When hooks or CI are enabled, normal commits must satisfy the provenance checks; bootstrap or migration exceptions must be explicit exceptions only.
36+
- Prefer the local surface template or directory `README.md` shape over ad hoc formatting when it defines one.
37+
38+
## Enforcement
39+
40+
When you write or update repo artifacts, adherence to the repo's ruleset is required.
41+
42+
- Do not invent a new document shape when the repo already provides a canonical surface, directory `README.md`, or explicit template.
43+
- Do not collapse truth, plans, decisions, research, inbox intake, and worklogs into one mixed artifact.
44+
- Do not replace normalized repo artifacts with freeform chat summaries.
45+
- If an artifact needs a justified local variation, keep the core fields and section order intact and make the smallest possible deviation.

‎AWARE-AGENT-PROMPT.md‎

Lines changed: 22 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,31 @@
1-
# Aware — Agent Development Prompt
1+
# Aware Agent Bootstrap
22

3-
## Overview
3+
Use this file as a pointer, not as the canonical product spec.
44

5-
Build a macOS menu bar app that prevents screen dimming/sleep by periodically checking for user presence via the FaceTime camera. No UI beyond a menu bar icon.
5+
## Canonical Docs
66

7-
---
7+
- `repo-operating-model.md` defines routing, provenance, and artifact rules.
8+
- `SPEC.md` holds durable product truth.
9+
- `STATUS.md` holds current operational reality.
10+
- `PLANS.md` holds accepted future direction only.
11+
- `INBOX.md` is the scratch surface for untriaged intake.
12+
- `records/decisions/` and `records/agent-worklogs/` store durable decisions and execution history.
813

9-
## Core Behavior
14+
## Working Rules
1015

11-
- Run as a menu bar–only app (`LSUIElement = YES`, no Dock icon).
12-
- Register display sleep prevention using `IOPMAssertionCreateWithName` with assertion type `kIOPMAssertionTypePreventUserIdleDisplaySleep`.
13-
- On a configurable polling interval (default: 30s), capture a single frame from the default `AVCaptureDevice` camera.
14-
- Run the frame through Vision's `VNDetectFaceRectanglesRequest`. If ≥1 face is detected, call `IOPMAssertionDeclareSystemActivity` to reset the idle timer and prevent dimming. If no face is detected, release the assertion and allow normal sleep behavior.
15-
- Camera is only active during the brief capture — not streaming continuously.
16+
- Do not duplicate product truth here; update the canonical repo docs instead.
17+
- Use stable IDs when creating artifacts: `IBX-*`, `RSH-*`, `DEC-*`, and `LOG-*`.
18+
- For normal post-bootstrap commits, include commit trailers: `project: aware`, `agent: <agent-id>`, `role: orchestrator|worker|subagent|operator`, and `artifacts: <artifact-id>[, ...]`.
19+
- Treat `README.md`, `docs/`, and `release-notes/` as user-facing or release-facing surfaces, not the canonical operating record.
1620

17-
---
21+
## Codebase Orientation
1822

19-
## Face Detection & Hardware Acceleration
23+
- `Aware/` contains the Swift and AppKit runtime.
24+
- `Aware.xcodeproj/` contains project settings and build metadata.
25+
- `.github/workflows/` contains build, release, and appcast automation.
26+
- `docs/` and `release-notes/` contain Sparkle setup and release-publishing docs.
2027

21-
- Use `VNDetectFaceRectanglesRequest` via the Vision framework. This is already ANE/GPU-accelerated on Apple Silicon via Core ML internally — no `VNCoreMLRequest` wrapper needed, and no CPU-bound alternatives.
22-
- Set the request's `revision` to `VNDetectFaceRectanglesRequestRevision3` (most accurate, still hardware-accelerated).
23-
- Pass the captured `CMSampleBuffer` directly to `VNImageRequestHandler` using the `.cvPixelBuffer` path — avoid JPEG/PNG encoding the frame, which wastes CPU cycles.
24-
- Downscale capture resolution: configure `AVCaptureSession` preset to `AVCaptureSessionPreset640x480` or `352x288`. Full-resolution frames are wasteful for binary face-present/absent detection.
25-
- Run `VNImageRequestHandler` on a background `DispatchQueue` with `.userInitiated` QoS — this is what lets the system route work to the ANE/GPU rather than the main thread CPU.
28+
## Bootstrap Records
2629

27-
---
28-
29-
## Stack
30-
31-
- **Language**: Swift
32-
- **UI**: AppKit (NSStatusItem, NSMenu)
33-
- **Camera**: AVFoundation
34-
- **Face detection**: Vision
35-
- **Sleep prevention**: IOKit
36-
- **Target**: macOS 13+
37-
- **Dependencies**: None (no third-party packages)
38-
39-
---
40-
41-
## Menu Bar Items
42-
43-
| Item | Behavior |
44-
|---|---|
45-
| Enable/Disable toggle | Persisted via `UserDefaults` |
46-
| Polling interval | 15s / 30s / 60s picker, persisted via `UserDefaults` |
47-
| Last detection status | Displays "Face detected", "No face", or "Disabled" |
48-
| Quit | Terminates the app |
49-
50-
---
51-
52-
## Permissions
53-
54-
- Request `NSCameraUsageDescription` at first enable.
55-
- If camera permission is denied, show an alert and disable the feature gracefully.
56-
- No network access. No data leaves the device.
57-
58-
---
59-
60-
## Project Structure
61-
62-
Single Xcode project. Separate service classes for distinct responsibilities:
63-
64-
- `PresenceDetector` — owns `AVCaptureSession` lifecycle and `VNDetectFaceRectanglesRequest` execution
65-
- `SleepAssertion` — wraps `IOPMAssertion` create/release logic
66-
- `MenuBarController` — owns both services, drives the polling loop via `DispatchSourceTimer`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu` (AppKit), presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`, presents menu via `NSStatusItem` and `NSMenu`
67-
68-
---
69-
70-
## Efficiency Summary
71-
72-
The key efficiency wins are:
73-
1. Low-resolution capture (`352x288` or `640x480`)
74-
2. Hardware-accelerated inference via Vision/ANE — no sustained CPU load
75-
3. Camera only wakes for a fraction of a second per polling interval, not a continuous stream
30+
- Decision: `DEC-20260409-001`
31+
- Worklog: `LOG-20260409-001`

‎CLAUDE.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
See `repo-operating-model.md` for the canonical repo operating rules.
2+
3+
# Claude Code Memory
4+
5+
This file exists so Claude Code can discover the repo's working rules automatically.
6+
7+
Treat `CLAUDE.md` as a thin compatibility layer, not a second source of truth. The canonical rules stay in `repo-operating-model.md`.
8+
9+
Also consult:
10+
11+
- `SPEC.md` for durable product or system truth
12+
- `STATUS.md` for current operational reality
13+
- `PLANS.md` for accepted future direction
14+
- `INBOX.md` for untriaged intake
15+
16+
If this repo includes reusable workflows, use `skills/<name>/SKILL.md` for bounded procedures and keep repo-wide policy in `repo-operating-model.md`.
17+
18+
When writing into `research/`, `records/`, or any future `upstream-intake/reports/`, read the local `README.md` first and mirror its default shape or canonical example by default.
19+
20+
Repo-specific reminders:
21+
22+
- Build verification: `xcodebuild -scheme Aware -configuration Debug -derivedDataPath build build`
23+
- Commit provenance setup: `scripts/install-hooks.sh`
24+
- Commit provenance checks: `scripts/check-commit-standards.sh <commit-message-file>` and `scripts/check-commit-range.sh <base> <head>`
25+
- `AWARE-AGENT-PROMPT.md` is legacy bootstrap orientation, not a canonical rules file
26+
27+
## Enforcement
28+
29+
When producing repo documents, you must enforce the repo's writing rules rather than treating them as suggestions.
30+
31+
- Use the canonical surface for the job.
32+
- Follow the local `README.md` shape or explicit template when one exists.
33+
- Preserve required provenance fields, stable IDs, and section boundaries.
34+
- When hooks or CI are enabled, produce commit messages that satisfy the provenance checks unless the commit is an explicit bootstrap or migration exception.
35+
- Do not replace normalized repo artifacts with freeform chat summaries.
36+
- If a request pressures you to break the ruleset, keep the repo artifact compliant and surface the mismatch explicitly.

‎INBOX.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Aware Inbox
2+
3+
This file is an ephemeral scratch disk for intake waiting to be triaged.
4+
5+
Rules:
6+
7+
- Keep it easy to append to from messenger, operator notes, or agent capture.
8+
- Remove entries once they are reflected into durable repo artifacts.
9+
- Keep the stable `IBX-*` id even after the inbox entry itself is later deleted.
10+
- Do not treat this file as durable truth.
11+
12+
## Active Intake
13+
14+
No active intake items are currently recorded.
15+
16+
When the next item arrives, use this default shape:
17+
18+
### IBX-YYYYMMDD-NNN
19+
20+
- Opened: `YYYY-MM-DD HH-mm-ss KST`
21+
- Recorded by agent:
22+
- Source:
23+
- Received:
24+
- Summary:
25+
- Triage status: `new` | `in review` | `reflected` | `dropped`
26+
- Suggested destination:
27+
- Related ids:
28+
- Notes:
29+
30+
## Purge Rule
31+
32+
Once an item has been reflected into `SPEC.md`, `STATUS.md`, `PLANS.md`, `research/`, `records/decisions/`, `records/agent-worklogs/`, or a future `upstream-intake/` module if the repo later adds one, remove the inbox entry.

‎PLANS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Aware Plans
2+
3+
This document contains accepted future direction only.
4+
Do not put raw brainstorms or untriaged intake here.
5+
6+
## Planning Rules
7+
8+
- Only accepted future direction belongs here.
9+
- Plans should be specific enough to guide execution later.
10+
- Product or architecture rationale should link to `DEC-*` records when relevant.
11+
- When a plan becomes current truth, reflect it into `SPEC.md` or `STATUS.md` and update this file.
12+
13+
## Approved Directions
14+
15+
### Incremental Repo-Template Normalization
16+
17+
- Outcome: future touched repo docs are normalized to their matching repo-template surface through repo-root entrypoints and local writing guides.
18+
- Why this is accepted: Aware already adopted repo-template, but some docs still need gradual shape normalization without a full-repo rewrite.
19+
- Expected value: document drift decreases over time while repo-specific truth and history remain intact.
20+
- Preconditions: read the matching local guide before editing and preserve existing IDs, dates, decisions, and historical facts.
21+
- Earliest likely start: `2026-04-09`
22+
- Related ids: `DEC-20260409-002`, `LOG-20260409-002`
23+
24+
## Sequencing
25+
26+
### Near Term
27+
28+
- Initiative: use `AGENTS.md`, `CLAUDE.md`, and the matching local guide on each future repo-doc edit
29+
- Why now: the enforcement entrypoints and writing guides now exist, but they only help if future edits use them
30+
- Dependencies: `repo-operating-model.md`, `AGENTS.md`, `CLAUDE.md`, and the local surface guides
31+
- Related ids: `DEC-20260409-002`, `LOG-20260409-002`
32+
33+
### Mid Term
34+
35+
- Initiative: none recorded
36+
- Why later: no accepted mid-term roadmap has been captured yet
37+
- Dependencies: future operator decisions
38+
- Related ids: none
39+
40+
### Deferred But Accepted
41+
42+
- Initiative: none recorded
43+
- Why deferred: no deferred accepted initiatives have been captured yet
44+
- Revisit trigger: add entries only after a direction is explicitly accepted
45+
- Related ids: none

‎SPEC.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Aware Spec
2+
3+
This file is the canonical statement of what Aware is supposed to be.
4+
Keep it durable. Do not use it as a changelog, inbox, or weekly narrative.
5+
6+
## Identity
7+
8+
- Project: `Aware`
9+
- Canonical repo: `https://github.com/LPFchan/Aware`
10+
- Project id: `aware`
11+
- Operator: `LPFchan`
12+
- Last updated: `2026-04-09`
13+
- Related decisions: `DEC-20260409-001`
14+
15+
## Product Thesis
16+
17+
Aware is a macOS menu bar utility that keeps the display awake when someone is actually at the Mac. It favors a low-friction, local-first experience: brief presence checks, minimal UI, and immediate fallback to normal sleep behavior when presence is not established.
18+
19+
## Primary User And Context
20+
21+
- Primary operator: `LPFchan`
22+
- Primary environment: macOS 13+ desktops and laptops with a built-in or default camera
23+
- Primary problem being solved: keep the display awake while the user is present at their desk without requiring constant keyboard or mouse input
24+
- Why this matters: passive screen dimming and screensavers are disruptive during reading, meetings, and other hands-off work
25+
26+
## Primary Workspace Object
27+
28+
The primary user-facing object is a menu bar app that manages display-idle prevention based on local presence signals.
29+
30+
## Canonical Interaction Model
31+
32+
1. The user launches Aware; it runs as an accessory app with a menu bar icon and no Dock presence.
33+
2. The user enables detection and grants camera permission if prompted.
34+
3. Aware polls on the selected interval and also treats recent keyboard or mouse activity as immediate presence.
35+
4. If another process already holds a sleep-prevention assertion, Aware skips the camera check and preserves awake state.
36+
5. If presence is confirmed, Aware resets the user-activity assertion; if not, it releases the assertion and updates the menu status.
37+
6. The user manages polling interval, open-at-login, update checks, and quit behavior from the menu.
38+
39+
## Core Capabilities
40+
41+
- Presence-aware idle prevention:
42+
- Why it exists: keep the display awake only when the user is present.
43+
- What must remain true: the app must release its assertion when presence is not established or the feature is disabled.
44+
- Menu bar-only control surface:
45+
- Why it exists: the feature should stay accessible without a persistent windowed UI.
46+
- What must remain true: enable or disable, status, interval selection, and quit must remain reachable from the menu bar.
47+
- Distribution and update surface:
48+
- Why it exists: releases need a repeatable path for DMG distribution and Sparkle-based updates.
49+
- What must remain true: tagged releases produce an installable DMG, and update metadata remains publishable without changing the runtime interaction model.
50+
51+
## Invariants
52+
53+
- Aware is a macOS accessory app (`LSUIElement`) with no Dock icon as the normal interaction model.
54+
- Presence detection uses local device signals only: recent HID activity, local camera capture, and on-device Vision face detection.
55+
- The app does not include telemetry or analytics; any network use is limited to release and update distribution surfaces such as Sparkle feeds and GitHub-hosted assets.
56+
- Camera-denied or camera-unavailable states must fail safe by disabling the feature and surfacing the condition to the user.
57+
58+
## Non-Goals
59+
60+
- Continuous video recording, remote monitoring, or person identification.
61+
- Full window-based productivity features beyond onboarding and menu bar control.
62+
- Cross-platform support outside macOS.
63+
64+
## Main Surfaces
65+
66+
- `Aware/`
67+
- Purpose: Swift/AppKit runtime, presence detection, sleep assertions, localization, and updater integration.
68+
- Notes: single Xcode project with direct system-framework integration.
69+
- `.github/workflows/`, `docs/`, and `release-notes/`
70+
- Purpose: build, release, Sparkle and appcast publishing, and operator-facing release documentation.
71+
- Notes: these remain user or release-facing surfaces; repo truth lives in the operating-model overlay docs.
72+
73+
## Success Criteria
74+
75+
- Aware prevents display sleep when the user is present and allows normal idle behavior when they are not.
76+
- The app remains lightweight to operate: menu bar only, clear status, bounded camera usage, and graceful permission handling.
77+
- The repo can ship repeatable DMG releases and localized update notes without losing the canonical product and process record.
78+

0 commit comments

Comments
 (0)