Skip to content

AGENTS.md

Latest commit

 

History

History
134 lines (97 loc) · 4.39 KB

AGENTS.md

File metadata and controls

134 lines (97 loc) · 4.39 KB

AGENTS.md

OpenWork is an open-source alternative to Claude Cowork.

Why OpenWork Exists

Cowork is closed-source and locked to Claude Max. We need an open alternative. Mobile-first matters. People want to run tasks from their phones. Slick UI is non-negotiable. The experience must feel premium, not utilitarian.

Agent Guidelines for development

  • Purpose-first UI: prioritize clarity, safety, and approachability for non-technical users.
  • Parity with OpenCode: anything the UI can do must map cleanly to OpenCode tools.
  • Prefer OpenCode primitives: represent concepts using OpenCode’s native surfaces first (folders/projects, .opencode, opencode.json, skills, plugins) before introducing new abstractions.
  • Self-referential: maintain a gitignored mirror of OpenCode at vendor/opencode for inspection.
  • Self-building: prefer prompts, skills, and composable primitives over bespoke logic.
  • Open source: keep the repo portable; no secrets committed.
  • Slick and fluid: 60fps animations, micro-interactions, premium feel.
  • Mobile-native: touch targets, gestures, and layouts optimized for small screens.

Technology Stack

Layer Technology
Desktop/Mobile shell Tauri 2.x
Frontend SolidJS + TailwindCSS
State Solid stores + IndexedDB
IPC Tauri commands + events
OpenCode integration Spawn CLI or embed binary

Repository Guidance

  • Write new PRDs under packages/app/pr/<prd-name>.md (see .opencode/skills/prd-conventions/SKILL.md).
  • Use MOTIVATIONS-PHILOSOPHY.md to understand the "why" of OpenWork so you can guide your decisions.

Local Structure

openwork/
  AGENTS.md                    # This file
  MOTIVATIONS-PHILOSOPHY.md     # Exhaustive PRD and user flow map
  .gitignore                    # Ignores vendor/opencode, node_modules, etc.
  .opencode/
  packages/
    app/
      src/
      public/
      pr/
      prd/
      package.json
    desktop/
      src-tauri/
      package.json

OpenCode SDK Usage

OpenWork integrates with OpenCode via:

  1. Non-interactive mode: opencode -p "prompt" -f json -q
  2. Database access: Read .opencode/opencode.db for sessions and messages.

Key primitives to expose:

  • session.Service — Task runs, history
  • message.Service — Chat bubbles, tool calls
  • agent.Service — Task execution, progress
  • permission.Service — Permission prompts
  • tools.BaseTool — Step-level actions

Safety + Accessibility

  • Default to least-privilege permissions and explicit user approvals.
  • Provide transparent status, progress, and reasoning at every step.
  • WCAG 2.1 AA compliance.
  • Screen reader labels for all interactive elements.

Performance Targets

Metric Target
First contentful paint <500ms
Time to interactive <1s
Animation frame rate 60fps
Interaction latency <100ms
Bundle size (JS) <200KB gzipped

Skill: SolidJS Patterns

When editing SolidJS UI (packages/app/src/**/*.tsx), consult:

  • .opencode/skills/solidjs-patterns/SKILL.md

This captures OpenWork’s preferred reactivity + UI state patterns (avoid global busy() deadlocks; use scoped async state).

Skill: Trigger a Release

OpenWork releases are built by GitHub Actions (Release App). A release is triggered by pushing a v* tag (e.g. v0.1.6).

Standard release (recommended)

  1. Ensure main is green and up to date.
  2. Bump versions (keep these in sync):
  • packages/app/package.json (version)
  • packages/desktop/package.json (version)
  • packages/desktop/src-tauri/tauri.conf.json (version)
  • packages/desktop/src-tauri/Cargo.toml (version)

You can bump all three non-interactively with:

  • pnpm bump:patch
  • pnpm bump:minor
  • pnpm bump:major
  • pnpm bump:set -- 0.1.21
  1. Merge the version bump to main.
  2. Create and push a tag:
    • git tag vX.Y.Z
    • git push origin vX.Y.Z

This triggers the workflow automatically (on: push.tags: v*).

Re-run / repair an existing release

If the workflow needs to be re-run for an existing tag (e.g. notarization retry), use workflow dispatch:

  • gh workflow run "Release App" --repo different-ai/openwork -f tag=vX.Y.Z

Verify

  • Runs: gh run list --repo different-ai/openwork --workflow "Release App" --limit 5
  • Release: gh release view vX.Y.Z --repo different-ai/openwork

Confirm the DMG assets are attached and versioned correctly.