Skip to content

feat: add Agents.MD and openspec support #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iparaskev merged 2 commits into from
Jan 27, 2026
Merged

feat: add Agents.MD and openspec support #237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
822784e
feat: add Agents.MD and openspec support
konsalex Jan 25, 2026
61072c9
add core agents.md file
iparaskev Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .cursor/commands/openspec-apply.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -->
27 changes: 27 additions & 0 deletions .cursor/commands/openspec-archive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -->
28 changes: 28 additions & 0 deletions .cursor/commands/openspec-proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -->
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,5 @@ dist-ssr
*__pycache__/

.yarn/install-state.gz

openspec/changes
Comment on lines 29 to +31
Copy link

@coderabbitai coderabbitai bot Jan 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, let's explore the repository structure to understand the context
git ls-files | head -20

Repository: gethopp/hopp

Length of output: 641

🏁 Script executed:

# Look for OpenSpec-related files and documentation
fd -t f "openspec" -o "OPENSPEC" -o "openspec" | head -20

Repository: gethopp/hopp

Length of output: 191

🏁 Script executed:

# Check for documentation files that might mention OpenSpec
fd -t f "README|readme|DOCS|docs|openspec" | grep -i "openspec\|spec\|change" | head -20

Repository: gethopp/hopp

Length of output: 38

🏁 Script executed:

# Examine the openspec directory structure if it exists
find . -type d -name "openspec" 2>/dev/null | head -5

Repository: gethopp/hopp

Length of output: 66

🏁 Script executed:

# Look at the .gitignore file in context to understand the changes
cat -n .gitignore | tail -20

Repository: gethopp/hopp

Length of output: 396

🏁 Script executed:

# Examine the openspec directory structure
ls -la openspec/ 2>/dev/null || echo "Directory not found"

Repository: gethopp/hopp

Length of output: 294

🏁 Script executed:

# Look for openspec documentation files
find ./openspec -type f 2>/dev/null | head -20

Repository: gethopp/hopp

Length of output: 98

🏁 Script executed:

# Check the OpenSpec cursor commands for context about proposals
cat .cursor/commands/openspec-proposal.md

Repository: gethopp/hopp

Length of output: 2585

🏁 Script executed:

# Check if there's any README or documentation in openspec
find ./openspec -name "README*" -o -name "readme*" -o -name "*.md" 2>/dev/null

Repository: gethopp/hopp

Length of output: 98

🏁 Script executed:

# Look at git history to understand when openspec/changes was added to gitignore
git log --oneline -n 20 -- .gitignore 2>/dev/null | head -20

Repository: gethopp/hopp

Length of output: 104

🏁 Script executed:

# Read the OpenSpec project documentation to understand the intended workflow
cat openspec/project.md

Repository: gethopp/hopp

Length of output: 6310

🏁 Script executed:

# Check the AGENTS.md for OpenSpec conventions
cat openspec/AGENTS.md | head -100

Repository: gethopp/hopp

Length of output: 4512

🏁 Script executed:

# Look for any existing openspec/changes directory content
find ./openspec/changes -type f 2>/dev/null | head -20

Repository: gethopp/hopp

Length of output: 38

🏁 Script executed:

# Check git status to see if openspec/changes is being ignored
git status --ignored openspec/ 2>/dev/null

Repository: gethopp/hopp

Length of output: 121

Remove openspec/changes from .gitignore.

The OpenSpec workflow documented in openspec/AGENTS.md and .cursor/commands/openspec-proposal.md explicitly instructs creating and storing change proposals, tasks, and design documents in openspec/changes/<id>/. These artifacts are meant to be versioned, reviewed, and later archived to openspec/changes/archive/ after deployment. Ignoring this directory prevents the entire spec-driven development workflow from being tracked in version control.

Suggested fix 
- openspec/changes
🤖 Prompt for AI Agents 
In @.gitignore around lines 29 - 31, The .gitignore currently excludes the
openspec/changes directory which prevents versioning of OpenSpec proposals and
docs; remove the "openspec/changes" entry from .gitignore so that files placed
under openspec/changes/<id>/ are tracked, reviewed, and can be archived later,
ensuring the OpenSpec workflow in openspec/AGENTS.md and
.cursor/commands/openspec-proposal.md works correctly; after removal, run git
add on any existing openspec/changes content and commit to start tracking those
artifacts.

88 changes: 88 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 -->
26 changes: 26 additions & 0 deletions core/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Loading
Loading