@joe-broadhead/opencode-gws 0.0.0-stage → 0.0.0

package/skills/opencode-gws-admin/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: opencode-gws-admin
+description: Load only when the user asks for admin reports, Apps Script, Workspace Events, Model Armor, or a workflow helper.
+opencode/autoinvoke: false
+---
+
+# High-risk Workspace services
+
+This skill is not loaded automatically. Use it only when the user asked for admin reports, Apps Script, Workspace Events, Model Armor, or a workflow helper.
+
+Search with `gws_catalog` and check `gws_schema` before you call. If `executable` is false, do not call that id. Deploy and watch never run. A helper with no adapter cannot run; use `alternative` when the catalog names one.
+
+## Admin gate
+
+An operation whose category is `admin` needs all of these before `gws_plan` will accept it:
+
+1. `admin.enabled` is true.
+2. The service is in `admin.allowedServices` (the default list is the services that have an admin-class entry).
+3. The plan includes a non-empty `reason` when `admin.requireReason` is true, which is the default.
+
+Then commit with `gws_admin` and only `{ "planId": "<planId>" }`. `gws_admin` asks every time. It does not offer Always. A user deny hides the tool.
+
+A read on one of these services is still a read: `gws_read`, no admin gate. A write that is not category `admin` still uses `gws_write` and the normal ask.
+
+Plugin policy cannot allow an admin call. A policy rule can only deny.
+
+## Admin reports
+
+Read-only at both access levels. The sign-in still needs the admin report scopes from the auth doc.
+
+Activity list, read. `fields` is required because this is a list:
+
+```json
+{
+  "operation": "admin-reports.activities.list",
+  "params": { "userKey": "all", "applicationName": "login" },
+  "fields": "items(id,actor,events),nextPageToken"
+}
+```
+
+Watching an activity feed is category `admin`, not a read. Plan it only when the user asked, with a reason, then commit with `gws_admin`:
+
+```json
+{
+  "operation": "admin-reports.activities.watch",
+  "params": { "userKey": "all", "applicationName": "login" },
+  "reason": "The user asked to watch login activity."
+}
+```
+
+`gws_schema` shows the watch body. Do not invent a channel.
+
+## Apps Script
+
+Read a project:
+
+```json
+{
+  "operation": "script.projects.get",
+  "params": { "scriptId": "SCRIPT_ID" }
+}
+```
+
+Creating a project is a write. Plan, then `gws_write`. Deployments and running a script never run. If catalog marks an id not executable, stop and tell the user.
+
+## Workspace Events
+
+Most subscription methods never run. A status read can:
+
+```json
+{
+  "operation": "events.operations.get",
+  "params": { "name": "operations/OPERATION_ID" }
+}
+```
+
+## Model Armor
+
+No access level requests Model Armor scopes. The account needs `https://www.googleapis.com/auth/cloud-platform` in `scopes`, and the user must sign in again so the grant is on the token. The Model Armor helpers cannot run. Do not invent a call. Tell the user, and use `gws_catalog` if they still want a Discovery method.
+
+## Workflow
+
+These three helpers are reads. They need the account to enable `workflow`, which uses the Gmail, Calendar, Tasks, and Drive scopes.
+
+```json
+{ "operation": "workflow.meeting-prep", "input": {} }
+```
+
+```json
+{ "operation": "workflow.standup-report", "input": {} }
+```
+
+```json
+{ "operation": "workflow.weekly-digest", "input": {} }
+```
+
+Other workflow helpers cannot run. Use the alternative `gws_catalog` names, and commit with that method's category tool.

package/skills/opencode-gws-recipes/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: opencode-gws-recipes
+description: Use when building a Gmail, Drive, Calendar, Docs, or Sheets request for gws_read or gws_plan.
+---
+
+# Recipes
+
+These are exact requests for the everyday Gmail, Drive, Calendar, Docs, and Sheets tasks. Copy the shape. Replace the placeholder ids and text. Confirm the parameters with `gws_schema` when the task is not one of these.
+
+Pass `account` only when `gws_status` shows more than one account. `fields` is required on list and search. A change is `gws_plan`, then the commit tool of the **returned** category, with only `{ "planId": "<planId>" }`. Show the preview first.
+
+If `gws_catalog` says `executable` is false, do not call that id. Use `alternative`.
+
+## Gmail
+
+Unread inbox, read:
+
+```json
+{
+  "operation": "gmail.users.messages.list",
+  "params": { "userId": "me", "q": "is:unread", "maxResults": 10 },
+  "fields": "messages(id,threadId),nextPageToken"
+}
+```
+
+One message, read. Prefer the helper when you want the text, not the raw payload:
+
+```json
+{
+  "operation": "gmail.read",
+  "input": { "id": "MESSAGE_ID", "format": "text" }
+}
+```
+
+Triage, read:
+
+```json
+{
+  "operation": "gmail.triage",
+  "input": { "max": 10, "query": "is:unread" }
+}
+```
+
+Send. Plan, show the preview, then `gws_send`. Send does not offer Always.
+
+```json
+{
+  "operation": "gmail.send",
+  "input": {
+    "to": "person@example.com",
+    "subject": "Hello",
+    "body": "Hello"
+  }
+}
+```
+
+Reply. Same commit tool, `gws_send`:
+
+```json
+{
+  "operation": "gmail.reply",
+  "input": { "messageId": "MESSAGE_ID", "body": "Thanks" }
+}
+```
+
+## Drive
+
+Recent files, read:
+
+```json
+{
+  "operation": "drive.files.list",
+  "params": { "q": "trashed = false", "pageSize": 20, "orderBy": "modifiedTime desc" },
+  "fields": "files(id,name,mimeType,modifiedTime),nextPageToken"
+}
+```
+
+One file's metadata, read:
+
+```json
+{
+  "operation": "drive.files.get",
+  "params": { "fileId": "FILE_ID" },
+  "fields": "id,name,mimeType,modifiedTime"
+}
+```
+
+Create a file, write. Plan, then `gws_write`. An upload path must be absolute and inside an allowed read root. `gws_schema` shows the upload field.
+
+```json
+{
+  "operation": "drive.files.create",
+  "body": { "name": "Notes.txt", "mimeType": "text/plain" }
+}
+```
+
+Move to trash. The plan category is **delete**, even if the manifest says write. Commit with `gws_delete`, not `gws_write`.
+
+```json
+{
+  "operation": "drive.files.update",
+  "params": { "fileId": "FILE_ID" },
+  "body": { "trashed": true }
+}
+```
+
+Share with one person. Plan category is share. Commit with `gws_share`. Share does not offer Always.
+
+```json
+{
+  "operation": "drive.permissions.create",
+  "params": { "fileId": "FILE_ID" },
+  "body": { "type": "user", "role": "reader", "emailAddress": "person@example.com" }
+}
+```
+
+## Calendar
+
+Today's agenda, read:
+
+```json
+{
+  "operation": "calendar.agenda",
+  "input": { "today": true }
+}
+```
+
+Events on the primary calendar, read:
+
+```json
+{
+  "operation": "calendar.events.list",
+  "params": { "calendarId": "primary", "maxResults": 10, "singleEvents": true, "orderBy": "startTime" },
+  "fields": "items(id,summary,start,end),nextPageToken"
+}
+```
+
+Create an event that does not email anyone. Plan category is write. Commit with `gws_write`.
+
+```json
+{
+  "operation": "calendar.events.insert",
+  "params": { "calendarId": "primary" },
+  "body": {
+    "summary": "Standup",
+    "start": { "dateTime": "2026-11-02T09:00:00+01:00" },
+    "end": { "dateTime": "2026-11-02T09:15:00+01:00" }
+  }
+}
+```
+
+Create or move an event that emails attendees (`sendUpdates` of `all` or `externalOnly`). The plan category is **send**. Commit with `gws_send`.
+
+```json
+{
+  "operation": "calendar.events.insert",
+  "params": { "calendarId": "primary", "sendUpdates": "all" },
+  "body": {
+    "summary": "Standup",
+    "start": { "dateTime": "2026-11-02T09:00:00+01:00" },
+    "end": { "dateTime": "2026-11-02T09:15:00+01:00" }
+  }
+}
+```
+
+## Docs
+
+Read a document:
+
+```json
+{
+  "operation": "docs.documents.get",
+  "params": { "documentId": "DOCUMENT_ID" }
+}
+```
+
+Create a document, write. Plan, then `gws_write`.
+
+```json
+{
+  "operation": "docs.documents.create",
+  "body": { "title": "Notes" }
+}
+```
+
+Insert text, write. Plan, then `gws_write`.
+
+```json
+{
+  "operation": "docs.documents.batchUpdate",
+  "params": { "documentId": "DOCUMENT_ID" },
+  "body": {
+    "requests": [
+      { "insertText": { "location": { "index": 1 }, "text": "Hello" } }
+    ]
+  }
+}
+```
+
+## Sheets
+
+Read a range. The helper is enough for a rectangular range:
+
+```json
+{
+  "operation": "sheets.read",
+  "input": { "spreadsheet": "SPREADSHEET_ID", "range": "Sheet1!A1:D20" }
+}
+```
+
+The method, when you need the raw values resource:
+
+```json
+{
+  "operation": "sheets.spreadsheets.values.get",
+  "params": { "spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:D20" }
+}
+```
+
+Append rows, write. Plan, then `gws_write`.
+
+```json
+{
+  "operation": "sheets.spreadsheets.values.append",
+  "params": {
+    "spreadsheetId": "SPREADSHEET_ID",
+    "range": "Sheet1!A1",
+    "valueInputOption": "USER_ENTERED"
+  },
+  "body": { "values": [["a", "b"]] }
+}
+```
+
+Create a spreadsheet, write. Plan, then `gws_write`.
+
+```json
+{
+  "operation": "sheets.spreadsheets.create",
+  "body": { "properties": { "title": "Notes" } }
+}
+```