feat: add Agents.MD and openspec support

.cursor/commands/openspec-apply.md

@@ -0,0 +1,23 @@
+---
+name: /openspec-apply
+id: openspec-apply
+category: OpenSpec
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

.cursor/commands/openspec-archive.md

@@ -0,0 +1,27 @@
+---
+name: /openspec-archive
+id: openspec-archive
+category: OpenSpec
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

.cursor/commands/openspec-proposal.md

@@ -0,0 +1,28 @@
+---
+name: /openspec-proposal
+id: openspec-proposal
+category: OpenSpec
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict --no-interactive` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

.gitignore

@@ -27,3 +27,5 @@ dist-ssr
 *__pycache__/
 
 .yarn/install-state.gz
+
+openspec/changes

AGENTS.md

@@ -0,0 +1,88 @@
+# Agent Development Guide for Hopp
+
+## Project Overview
+
+Hopp is an open-source pair programming app with screen sharing, remote control, and multi-user rooms. Built with Tauri (desktop), Go (backend), and Rust (core engine).
+
+## Directory Structure
+
+- `backend/` — Go API server (Echo, PostgreSQL, Redis)
+- `core/` — Rust screen capture/remote control engine
+- `tauri/` — Tauri desktop app (React + TypeScript frontend)
+- `web-app/` — React web application
+- `docs/` — Astro documentation site
+
+## Commands
+
+All commands use [Taskfile](https://taskfile.dev). Run `task --list` in any directory to see available tasks.
+
+Avoid running the following commands as an agent, as this is preferred to run from a user in their terminal and navigate in the Desktop app.
+
+**Backend (Go):**
+```bash
+cd backend
+task run          # Run with hot reload (Air)
+task test         # Run tests
+```
+
+**Core (Rust):**
+```bash
+cd core
+cargo build
+cargo test
+cargo fmt         # Format code
+```
+
+**Tauri App:**
+```bash
+cd tauri
+task dev          # Dev mode with hot reload
+task build        # Production build
+```
+
+**Web App:**
+```bash
+cd web-app
+yarn dev
+yarn build
+```
+
+## Code Style
+
+- **JS/TS:** Prettier (120 cols). Runs via pre-commit.
+- **Rust:** `cargo fmt` per crate (`core/`, `tauri/src-tauri/`).
+- **Go:** `gofmt` + `golangci-lint` (config: `.golangcli.yml`).
+
+Pre-commit hooks enforce all formatting automatically.
+
+## Testing
+
+- **Go:** Integration tests in `backend/test/integration/`
+- **Rust:** Unit tests + visual integration tests in `core/tests/`
+- **Frontend:** Linting + typechecking (no unit test runner configured)
+
+## Key Conventions
+
+- Use `@` alias for imports in TS/React code (maps to `src/`)
+- API contracts defined in `backend/api-files/openapi.yaml`
+- Desktop app launches `hopp_core` binary and communicates over socket
+- Cross-platform: macOS, Windows, Linux all supported
+
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

core/AGENTS.md

@@ -0,0 +1,26 @@
+# Core Agent Guide
+
+## Scope
+This directory contains the Rust screen capture and remote control engine (`hopp_core`) plus supporting crates (`socket_lib`, `sentry_utils`).
+
+## Key Commands
+- See `Taskfile.yml` in this directory for the full, up-to-date command list.
+
+## Formatting & Linting
+- `cargo fmt` is required (pre-commit formats staged Rust files).
+- CI runs `cargo fmt --all -- --check` and `cargo clippy -D warnings`.
+- Rust edition: 2021.
+
+## Testing
+- Do not run core tests as an agent.
+- For validation, only use build commands (see `Taskfile.yml`).
+- Full testing details live in `tests/README.md`.
+
+## Conventions & Structure
+- Platform-specific modules live in `src/**/{linux,macos,windows}.rs`.
+- Core subsystems: `capture/`, `graphics/`, `input/`, `room_service/`.
+- Logging uses `env_logger`; set `RUST_LOG=hopp_core=info` (use `debug` only when needed).
+
+## Related Docs
+- `README.md` for architecture and diagrams.
+- `tests/README.md` for test setup and commands (manual only).