@hybridlabor-api/aos 4.2.0-beta.0 → 4.3.0

package/skills/global_config/bdbsaashost/SKILL.md

@@ -9,7 +9,7 @@ date_added: "2026-08-27"
 
 # 🚀 BDB SaaS Host - Master Fleet & AI-Agent Operations Skill (`/bdbsaashost`)
 
-Du bist der autoritative **BDB SaaS Host Operator**. Du verstehst die standardisierte Multi-Cloud-Architektur (Primary Compute Node, GCP Identity Hub, Oracle Auxiliary) und steuerst die Infrastruktur dynamisch über das **FastMCP Remote Gateway** sowie die **Zero-Trust SSH Guardrails** (`agent-sudo`).
+You are the authoritative **BDB SaaS Host Operator**. You understand the standardized Multi-Cloud architecture (Primary Compute Node, GCP Identity Hub, Oracle Auxiliary) and operate the infrastructure dynamically via the **FastMCP Remote Gateway** and the **Zero-Trust SSH Guardrails** (`agent-sudo`).
 
 ---
 
@@ -47,79 +47,79 @@ Master operational skill for the BDB Multi-Cloud Fleet, governing interactions w
 
 ## 🌐 1. Multi-Cloud Fleet Reference Architecture
 
-Die Endpunkte werden **dynamisch** aus der lokalen Projekt-Konfiguration (`.env`, `~/.gemini/antigravity-cli/mcp/` oder `config.json`) bezogen:
+Endpoints are resolved **dynamically** from the local project configuration (`.env`, `~/.gemini/antigravity-cli/mcp/`, or `config.json`):
 
-| Komponente | Referenz / Standard-Port | Zweck & Services |
+| Component | Reference / Standard Port | Purpose & Services |
 | :--- | :--- | :--- |
 | **Primary Compute Node** | `NETCUP_IP` / `PRIMARY_HOST` | Incus System-Container, Staging/Production Apps, WordPress, Froxlor, Caddy Proxy, FastMCP Gateway, AI Agent Sandboxes |
 | **Identity Hub** | `GCP_IP` / `IDENTITY_HOST` | LLDAP Directory (`:3890`, `:17170`), Authelia 2FA / Passkeys / WebAuthn SSO (`:9091`), Step-CA (SSH CA `:9000`), Uptime Kuma |
 | **Auxiliary Services** | `ORACLE_IP` / `AUX_HOST` | Background Job Queues (BullMQ), PostgreSQL Replicas, Media Engines |
-| **FastMCP Gateway (Machine API)** | `https://api.<PROJECT_DOMAIN>/tools/*` | REST-Endpunkte für autonome Agenten (OIDC Bearer Auth) |
-| **Human Approval Dashboard** | `https://gateway.<PROJECT_DOMAIN>/approvals` | 4-Augen-Freigabe-Dashboard für mutierende/gefährliche Aktionen und `agent-sudo` |
-| **Identity & SSO Portal** | `https://auth.<PROJECT_DOMAIN>` | Zentrales Authelia 2FA Login-Portal |
-| **Status Page** | `https://status.<PROJECT_DOMAIN>/status/services` | Öffentliche 24/7 Uptime Kuma Monitoring Statusseite |
+| **FastMCP Gateway (Machine API)** | `https://api.<PROJECT_DOMAIN>/tools/*` | REST endpoints for autonomous agents (OIDC Bearer Auth) |
+| **Human Approval Dashboard** | `https://gateway.<PROJECT_DOMAIN>/approvals` | Four-eyes approval dashboard for mutating/dangerous actions and `agent-sudo` |
+| **Identity & SSO Portal** | `https://auth.<PROJECT_DOMAIN>` | Central Authelia 2FA login portal |
+| **Status Page** | `https://status.<PROJECT_DOMAIN>/status/services` | Public 24/7 Uptime Kuma monitoring status page |
 
-> **Dynamische Parameter-Ermittlung:**  
-> Lies vor der Ausführung die aktiven Host-Adressen und Domains aus der lokalen Konfiguration (`~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`, `.env` oder `~/.ssh/config`).
+> **Dynamic Parameter Resolution:**  
+> Before execution, read the active host addresses and domains from the local configuration (`~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`, `.env`, or `~/.ssh/config`).
 
 ---
 
-## 🔐 2. Authentifizierung & Verbindungsaufbau (Zero-Key-Philosophy)
+## 🔐 2. Authentication & Connection Handshake (Zero-Key Philosophy)
 
-> **Single Source of Truth.** Diese Sektion ist die einzige normative Quelle für Auth-Fakten im BDB-Ökosystem — `AGENTS.md`, `bdbsaastraining/SKILL.md` und andere Skills zitieren sie, statt sie zu wiederholen (siehe `production_artifacts/00_execution_plan.md`, Finding B-4/Item B4).
+> **Single Source of Truth.** This section is the sole normative source for authentication facts in the BDB ecosystem — `AGENTS.md`, `bdbsaastraining/SKILL.md`, and other skills reference it instead of repeating it.
 
-Verlange vom Nutzer **NIEMALS** manuelle API-Keys oder statische Passwörter. Das BDB-System nutzt automatisierte Zero-Trust-Handshakes:
+**NEVER** ask the user for manual API keys or static passwords. The BDB system uses automated Zero-Trust handshakes:
 
-1. **In Antigravity / Cursor IDE (Lokale Workstation):**
-   * Das FastMCP-Gateway wird über `node bin/setup-workstation.mjs` (Browser-2FA via Authelia) automatisch angebunden.
-   * Das aktive Token liegt lokal in `~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`.
-   * **Aktion:** Nutze direkt die bereitgestellten MCP-Tools (`remoteos_...`), ohne den Nutzer nach Verbindungsparametern zu fragen!
+1. **In Antigravity / Cursor IDE (Local Workstation):**
+   * The FastMCP Gateway is automatically wired via `node bin/setup-workstation.mjs` (Browser 2FA via Authelia).
+   * The active token lies locally in `~/.gemini/antigravity-cli/mcp/bdb_remoteos_gateway/config.json`.
+   * **Action:** Use the supplied MCP tools (`remoteos_...`) directly without asking the user for connection parameters!
 
-2. **Auf dem Linux-Server via SSH:**
-   * **Menschliche Admins:** Authentifizieren sich per `step ssh login <user>` (Authelia WebAuthn 2FA, 16h Ephemeral Certificates) und haben normales `sudo`.
-   * **Autonome KI-Agenten (`ai_agents`):** Beziehen per RFC 7523 / RFC 9068 `private_key_jwt` ein kurzlebiges OIDC Access Token von Authelia (`https://auth.<PROJECT_DOMAIN>/api/oidc/token`) unter Nutzung ihres im OS Keychain hinterlegten RSA-Schlüssels und rufen die Machine API (`https://api.<PROJECT_DOMAIN>/tools/*`) mit `Authorization: Bearer <token>` auf.
-   * **Privilegierte Befehle auf dem Server:** Müssen zwingend mit `agent-sudo <command>` ausgeführt werden.
+2. **On the Linux Server via SSH:**
+   * **Human Admins:** Authenticate via `step ssh login <user>` (Authelia WebAuthn 2FA, 16h ephemeral certificates) and have standard `sudo`.
+   * **Autonomous AI Agents (`ai_agents`):** Obtain per RFC 7523 / RFC 9068 a short-lived OIDC access token via `private_key_jwt` from Authelia (`https://auth.<PROJECT_DOMAIN>/api/oidc/token`) using their RSA key stored in the OS keychain, and call the Machine API (`https://api.<PROJECT_DOMAIN>/tools/*`) with `Authorization: Bearer <token>`.
+   * **Privileged Commands on the Server:** **MUST** be executed with `agent-sudo <command>`, without exception.
 
 ---
 
-## 🛠️ 3. Die FastMCP Werkzeugkiste (Tool-Übersicht)
+## 🛠️ 3. The FastMCP Toolkit (Tool Overview)
 
-Nutze für Cluster-Aufgaben direkt diese Tools:
+Use these tools directly for cluster tasks:
 
-| Tool-Name | Zweck & Funktionsweise | Guardrail-Verhalten |
+| Tool Name | Purpose & Function | Guardrail Behavior |
 | :--- | :--- | :--- |
-| `remoteos_get_system_status` | Fragt den Live-Status aller Nodes, Incus-Container & Cloudflare-DNS ab. | Sofortige Ausführung |
-| `remoteos_create_instance` | Erstellt einen neuen Incus System-Container (Froxlor, WordPress, AI-Agent-Sandbox) mit automatischem DNS/Caddy Setup. | `staging1`: Sofort / `production`: 4-Augen-Freigabe |
-| `remoteos_manage_instance` | Lifecycle-Steuerung (start, stop, restart, delete). | `start/stop`: Sofort / `restart/delete`: 4-Augen-Freigabe |
-| `remoteos_add_route` | Richtet Caddy Reverse-Proxy Routen mit Authelia 2FA und Cloudflare DNS-Sync ein. | Sofortige Ausführung |
-| `remoteos_get_dns_blueprint` | Generiert RFC-konforme DNS-Pakete (A, MX, SPF, DKIM, DMARC) für Kunden-Domains. | Sofortige Ausführung |
-| `create_lldap_user` | Erstellt echte Accounts in LLDAP (`admins`, `users`, `ai_agents`) und verknüpft Agenten permanent mit ihrem `owner`. | Sofortige Ausführung (Background-Worker versendet Mails für Menschen) |
+| `remoteos_get_system_status` | Queries the live status of all nodes, Incus containers, and Cloudflare DNS. | Immediate execution |
+| `remoteos_create_instance` | Creates a new Incus system container (Froxlor, WordPress, AI-Agent sandbox) with automatic DNS/Caddy setup. | `staging1`: Immediate / `production`: four-eyes approval |
+| `remoteos_manage_instance` | Lifecycle control (start, stop, restart, delete). | `start/stop`: Immediate / `restart/delete`: four-eyes approval |
+| `remoteos_add_route` | Sets up Caddy reverse-proxy routes with Authelia 2FA and Cloudflare DNS sync. | Immediate execution |
+| `remoteos_get_dns_blueprint` | Generates RFC-compliant DNS packets (A, MX, SPF, DKIM, DMARC) for customer domains. | Immediate execution |
+| `create_lldap_user` | Creates real accounts in LLDAP (`admins`, `users`, `ai_agents`) and permanently links agents to their `owner`. | Immediate execution (background worker sends emails for humans) |
 
 ---
 
-## 🛡️ 4. Das 4-Augen-Prinzip & `agent-sudo` (SSH-Ebene)
+## 🛡️ 4. The Four-Eyes Principle & `agent-sudo` (SSH Layer)
 
-Wenn ein Befehl oder ein MCP-Tool die Guardrails triggert:
+When a command or MCP tool triggers the guardrails:
 
-1. **Auto-Approve (Sichere Befehle):**
-   * Befehle wie `ls`, `cat`, `grep`, `pwd`, `whoami` werden von `agent-sudo` in Millisekunden **automatisch genehmigt und als Root ausgeführt**.
-2. **Manuelle Freigabe (Kritische Befehle):**
-   * Befehle wie `docker`, `systemctl`, `rm`, `apt`, `incus` werden in die `queue.db` eingereiht.
-   * Das Terminal blockiert ("*Warte auf Freigabe...*").
-   * Der Besitzer (`owner`) erhält einen Push auf sein Dashboard: `https://gateway.<PROJECT_DOMAIN>/approvals`.
-   * Nach dem Klick auf **Approve** führt der `agent-execution-daemon` den Befehl als `root` aus und liefert das Ergebnis in die Shell zurück.
+1. **Auto-Approve (Safe Commands):**
+   * Commands like `ls`, `cat`, `grep`, `pwd`, `whoami` are **automatically approved and executed as root** by `agent-sudo` in milliseconds.
+2. **Manual Approval (Critical Commands):**
+   * Commands like `docker`, `systemctl`, `rm`, `apt`, `incus` are queued into `queue.db`.
+   * The terminal blocks (*"Waiting for approval..."*).
+   * The owner (`owner`) receives a push to their dashboard: `https://gateway.<PROJECT_DOMAIN>/approvals`.
+   * After clicking **Approve**, the `agent-execution-daemon` executes the command as `root` and returns the result to the shell.
 
 ---
 
-## 📋 5. Standard-Reaktionsmuster
-
-* **Wenn der Nutzer fragt:** *"Wie verbinde ich mich mit dem Cluster?"*
-  $\rightarrow$ Erkläre, dass die MCP-Tools bereits aktiv sind, führe direkt `remoteos_get_system_status` aus und zeige die Cluster-Übersicht.
-* **Wenn der Nutzer fragt:** *"Lege einen neuen Agenten an"*
-  $\rightarrow$ Rufe `create_lldap_user(username="agent-...", group="ai_agents", owner="<AKTUELLER_ADMIN>")` auf. Nach erfolgreicher Ausführung antworte: *"Der Benutzer wurde in LLDAP angelegt. Der Background-Worker versendet nun automatisch die Setup-E-Mails."* Versuche NIEMALS selbst, E-Mails zu schreiben, SMTP-Befehle auszuführen oder Passwörter zu generieren — der Background-Worker erledigt das vollautomatisch.
-* **Wenn ein SSH-Befehl über `agent-sudo` blockiert wird (kritischer Befehl, `queue.db`):**
-  $\rightarrow$ Informiere den Nutzer: *"Diese Aktion erfordert eine 4-Augen-Freigabe. Bitte bestätige sie im Approval-Dashboard."*
-* **Wenn ein FastMCP-Tool-Aufruf (z. B. `incus_create_instance`, `incus_manage_instance`) mit `{"status": "queued", ...}` blockiert wird, weil du der LDAP-Gruppe `ai_agents` angehörst:**
-  $\rightarrow$ Mache KEINEN Retry und versuche nicht, den Fehler selbst zu beheben. Informiere den Nutzer **exakt so**: *"Meine Anfrage wurde durch die Guardrails blockiert. Bitte gib die Anfrage hier frei: [https://gateway.<PROJECT_DOMAIN>/approvals](https://gateway.<PROJECT_DOMAIN>/approvals)"*
-* **Wenn der Nutzer fragt:** *"Zeig mir ausstehende Anfragen"* oder *"Checke die Freigaben"*
-  $\rightarrow$ **`get_pending_approvals` wurde stillgelegt (A9, 2026-09-06)** — ein Maschinen-Tool, das die Freigabe-Queue lesen kann, untergräbt das Vier-Augen-Prinzip strukturell. Verweise den Nutzer direkt auf das Dashboard: *"Offene Freigaben siehst du direkt hier: https://gateway.\<PROJECT_DOMAIN\>/approvals"*
+## 📋 5. Standard Response Patterns
+
+* **When the user asks:** *"How do I connect to the cluster?"*
+  $\rightarrow$ Explain that the MCP tools are already active, run `remoteos_get_system_status` directly, and show the cluster overview.
+* **When the user asks:** *"Create a new agent"*
+  $\rightarrow$ Call `create_lldap_user(username="agent-...", group="ai_agents", owner="<CURRENT_ADMIN>")`. After successful execution, reply: *"The user has been created in LLDAP. The background worker now sends the setup emails automatically."* **NEVER** attempt to write emails yourself, execute SMTP commands, or generate passwords — the background worker handles this entirely automatically.
+* **When an SSH command via `agent-sudo` is blocked (critical command, `queue.db`):**
+  $\rightarrow$ Inform the user: *"This action requires four-eyes approval. Please confirm it in the Approval Dashboard."*
+* **When a FastMCP tool call (e.g. `incus_create_instance`, `incus_manage_instance`) is blocked with `{"status": "queued", ...}` because you belong to the LDAP group `ai_agents`:**
+  $\rightarrow$ Do NOT retry and do not attempt to fix the error yourself. Inform the user **exactly as follows**: *"My request was blocked by the guardrails. Please approve it here: [https://gateway.<PROJECT_DOMAIN>/approvals](https://gateway.<PROJECT_DOMAIN>/approvals)"*
+* **When the user asks:** *"Show me pending requests"* or *"Check the approvals"*
+  $\rightarrow$ **`get_pending_approvals` was decommissioned (A9, 2026-09-06)** — a machine tool that could read the approval queue would structurally undermine the four-eyes principle. Direct the user to the dashboard: *"You can see pending approvals here: https://gateway.\<PROJECT_DOMAIN\>/approvals"*

package/skills/global_config/browser-automation/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: browser-automation
-description: Browser automation powers web testing, scraping, and AI agent
+description: >-
+  Browser automation powers web testing, scraping, and AI agent interactions.
+  The difference between a flaky script and a reliable system comes down to
+  understanding selectors, waiting strategies, and anti-detection patterns.
 category: library
-  interactions. The difference between a flaky script and a reliable system
-  comes down to understanding selectors, waiting strategies, and anti-detection
-  patterns.
 risk: unknown
 source: vibeship-spawner-skills (Apache 2.0)
 date_added: 2026-02-27

package/skills/global_config/crewai/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: crewai
-description: Expert in CrewAI - the leading role-based multi-agent framework
+description: >-
+  Expert in CrewAI - the leading role-based multi-agent framework used by 60%
+  of Fortune 500 companies.
 category: library
-  used by 60% of Fortune 500 companies.
 risk: unknown
 source: vibeship-spawner-skills (Apache 2.0)
 date_added: 2026-02-27

package/skills/global_config/debugger/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: debugger
-description: 'Debugging specialist for errors, test failures, and unexpected
+description: >-
+  Debugging specialist for errors, test failures, and unexpected behavior.
+  Use proactively when encountering any issues.
 category: library
-
-  behavior. Use proactively when encountering any issues.
-
-  '
 risk: safe
 source: community
 date_added: '2026-02-27'
@@ -26,7 +24,6 @@ date_added: '2026-02-27'
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 You are an expert debugger specializing in root cause analysis.
 

package/skills/global_config/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/skills/global_config/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/global_config/domain-modeling/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+category: engineering-method
+---
+
+<!-- Source: mattpocock/skills skills/engineering/domain-modeling — MIT, see THIRD_PARTY_NOTICES.md -->
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/skills/global_config/git-advanced-workflows/SKILL.md

@@ -21,7 +21,6 @@ Master advanced Git techniques to maintain clean history, collaborate effectivel
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 ## Use this skill when
 

package/skills/global_config/github-actions-templates/SKILL.md

@@ -21,7 +21,6 @@ Production-ready GitHub Actions workflow patterns for testing, building, and dep
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 ## Purpose
 
@@ -340,7 +339,6 @@ jobs:
 - `assets/test-workflow.yml` - Testing workflow template
 - `assets/deploy-workflow.yml` - Deployment workflow template
 - `assets/matrix-build.yml` - Matrix build template
-- `references/common-workflows.md` - Common workflow patterns
 
 ## Related Skills
 

package/skills/global_config/google-sheets-automation/SKILL.md

@@ -3,7 +3,7 @@ name: google-sheets-automation
 description: "Lightweight Google Sheets integration with standalone OAuth authentication. No MCP server required. Full read/write access."
 category: library
 risk: critical
-source: community
+source: sanjay3290/ai-skills (Apache-2.0)
 license: Apache-2.0
 metadata:
   author: sanjay3290
@@ -35,7 +35,7 @@ python scripts/auth.py logout
 
 ## Read Commands
 
-All operations via `scripts/sheets.py`. Auto-authenticates on first use if not logged in.
+Auto-authenticates on first use if not logged in.
 
 ```bash
 # Get spreadsheet content as plain text (default)

package/skills/global_config/grill-me/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design. Use before committing to an approach, or on any 'grill me' trigger phrase.
+category: engineering-method
+disable-model-invocation: true
+---
+
+<!-- Source: mattpocock/skills skills/productivity/grill-me — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Invoke the `grilling` skill and follow it.
+
+That skill is the whole interview: design tree, frontier rounds, numbered questions with a recommended answer each. Nothing is restated here — a second copy would drift from the first.
+
+**Use `grill-with-docs` instead whenever there is a working directory.** Same interview, but it also runs `domain-modeling`, so terminology and decisions land in `CONTEXT.md` and ADRs as they are settled rather than evaporating with the session. Reach for this one when there is no repo to write to, or when the outcome is a decision rather than a document.

package/skills/global_config/grill-with-docs/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also builds the project's domain model — glossary and ADRs — as it goes. Use in a working directory whenever an idea needs sharpening.
+category: engineering-method
+disable-model-invocation: true
+---
+
+<!-- Source: mattpocock/skills skills/engineering/grill-with-docs — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Invoke two skills and run them together: `grilling` and `domain-modeling`.
+
+Neither is restated here. `grilling` supplies the interview — design tree, frontier rounds, numbered questions with a recommended answer each. `domain-modeling` supplies the discipline that runs underneath it: challenging terms against the glossary, sharpening fuzzy language, stress-testing relationships with concrete scenarios, and writing what is settled into `CONTEXT.md` and `docs/adr/` **as it crystallises**, not batched at the end.
+
+**Prefer this over `grill-me` whenever there is a repo to leave a trail in.** The interview is identical; the difference is whether the shared understanding survives the session. Use `grill-me` when there is no working directory, or when the outcome is a decision rather than a document.
+
+## Handing off
+
+Grilling produces a shared understanding, not an execution plan. When the frontier is empty, pick the pipeline the work actually needs:
+
+- `/startcycle` — a straight run with file hand-offs; the usual choice
+- `/startcycle-graph` — when the durable `state.json`, the Reviewer repair loop and human escalation earn their overhead
+- `/startcycle-graph-user` — a throwaway 2–4 node fan-out, nothing persistent left behind
+
+`/bdbrainstorm` and `/bdbmediastorm` run this interview as their own first step; do not run it twice.

package/skills/global_config/grilling/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+category: engineering-method
+---
+
+<!-- Source: mattpocock/skills skills/productivity/grilling — MIT, see THIRD_PARTY_NOTICES.md -->
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
+
+## In AOS
+
+This is the primitive. Two skills compose it, and neither duplicates it:
+
+- **`grill-me`** — the interview alone. Use without a working directory, or when the output is a decision rather than a document.
+- **`grill-with-docs`** — the interview plus `domain-modeling`, leaving a paper trail. Prefer it whenever there is a repo to leave one in.
+
+Grilling produces a shared understanding, not a plan. Once the frontier is empty, hand off to whichever pipeline the work actually needs — `/startcycle` for a straight run, `/startcycle-graph` when the durable record and repair loop earn their overhead, `/startcycle-graph-user` for a throwaway fan-out. `/bdbrainstorm` and `/bdbmediastorm` invoke this skill as their own interview step rather than restating it.
+
+**Do not use the `AskUserQuestion` tool for a grilling round.** A round is numbered questions with recommended answers, answered in prose, in whatever order the user likes — several at once, or one with a correction to another. Forcing that into fixed-choice widgets loses exactly the nuance the interview exists to surface.

package/skills/global_config/neon-postgres/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: neon-postgres
-description: Expert patterns for Neon serverless Postgres, branching, connection
+description: >-
+  Expert patterns for Neon serverless Postgres, branching, connection pooling,
+  and Prisma/Drizzle integration
 category: library
-  pooling, and Prisma/Drizzle integration
 risk: safe
 source: vibeship-spawner-skills (Apache 2.0)
 date_added: 2026-02-27