Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions .cursor/rules/devops/agentic-automation.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ Rules governing agent-driven automation in DevOps surfaces — Cursor skills, ho
## Read-only default

- **Skills default to read-only.** Mutations to the local repo, the remote (GitHub state, releases, branch protection), or external systems (cloud, k8s, Slack, Asana) require explicit user opt-in per call.
- **The `pr-review` pattern is the reference**: print the exact command, wait for user confirmation, then execute. Never auto-execute.
- **The `qv-pr-review` pattern is the reference**: print the exact command, wait for user confirmation, then execute. Never auto-execute.
- **No silent file mutations** to the user's working tree. If a skill writes outside `/tmp/` or its own `_lib/` cache, it announces what and why first.
- **No silent git mutations**: forbidden without explicit user instruction — `git switch`, `git checkout` (any ref/file), `git reset`, `git restore`, `git stash`, `git pull`, `git merge`, `git rebase`, `git cherry-pick`, `git clean`, `gh pr checkout`. (See `.cursor/skills/pr-review/SKILL.md` "Safety rules" section for the canonical wording.)
- **No silent git mutations**: forbidden without explicit user instruction — `git switch`, `git checkout` (any ref/file), `git reset`, `git restore`, `git stash`, `git pull`, `git merge`, `git rebase`, `git cherry-pick`, `git clean`, `gh pr checkout`. (See `.cursor/skills/qv-pr-review/SKILL.md` "Safety rules" section for the canonical wording.)

## Plan-then-apply for state changes

Expand All @@ -44,7 +44,7 @@ Rules governing agent-driven automation in DevOps surfaces — Cursor skills, ho
## Idempotency

- **Skills must be idempotent.** Re-running with identical inputs produces the same effect, or reports "already applied" without making changes.
- **Generated artifacts (NOTICE files, changelog entries, generated docs) sort deterministically** so re-runs produce byte-identical output and clean diffs (the `notice-generate` skill is the reference).
- **Generated artifacts (NOTICE files, changelog entries, generated docs) sort deterministically** so re-runs produce byte-identical output and clean diffs (the `qv-notice-generate` skill is the reference).
- **Network-dependent skills** cache responses where reasonable (`/tmp/<skill>-<id>.json`) and document staleness.

## Validation before success
Expand Down Expand Up @@ -78,15 +78,15 @@ Rules governing agent-driven automation in DevOps surfaces — Cursor skills, ho

## Bounded resource use

- **Bound shell-call count per skill.** State an explicit budget in the skill's "Efficiency rules" section (the `pr-review` skill caps at ~5–8 calls; treat that as the ceiling unless justified).
- **Bound shell-call count per skill.** State an explicit budget in the skill's "Efficiency rules" section (the `qv-pr-review` skill caps at ~5–8 calls; treat that as the ceiling unless justified).
- **Cache fetched data once per session** (`/tmp/<skill>-<id>.json`). Never re-fetch the same PR/run/file in one session.
- **Use dedicated tools, not shell.** `Read` instead of `cat`/`head`/`tail`, `Grep` instead of `grep`/`rg`, `Glob` instead of `find`, `Write`/`StrReplace` instead of `echo >` / heredoc.
- **Prefer scripts in `_lib/<domain>/`** over inline shell pipelines. Scripts are testable, deterministic, and share-able across skills.

## Skill authoring conventions

- **One skill = one capability.** Don't compose unrelated workflows in a single skill.
- **Naming**: kebab-case, prefix-grouped (`devops-*`, `sdk-*`, `addon-*`, `pr-*`).
- **Naming**: kebab-case, all custom repo skills use the `qv-` prefix, then pod or domain segment (`qv-devops-*`, `qv-sdk-*`, `qv-addon-*`, `qv-pr-*`).
- **`SKILL.md` body ≤ 500 lines.** Push detail to `references/*.md` and link one level deep.
- **Slash-command discoverability**: include `/<skill-name>` in the description.
- **Auto-invoke vs explicit**: `disable-model-invocation: true` for any skill that mutates state, posts publicly, or runs slow / expensive tooling. Auto-invoke only for read-only, fast, contextually obvious helpers.
Expand Down
4 changes: 2 additions & 2 deletions .cursor/rules/devops/main.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Owns CI/CD pipelines (GitHub Actions workflows + composite actions), repo-wide a
| `.cursor/rules/devops/secrets-and-credentials.mdc` | `.github/**`, `scripts/**` | Anything that can read, derive, or transmit a secret |
| `.cursor/rules/devops/agentic-automation.mdc` | `.cursor/skills/**`, `.cursor/rules/**`, `.cursor/hooks/**`, `.github/workflows/**`, `.github/scripts/**`, `scripts/**` | Authoring skills, hooks, MCP integrations, or any AI-driven DevOps workflow |

Commit message and PR title format guidance lives in the [`devops-pr-create`](../../skills/devops-pr-create/SKILL.md) skill — invoke it explicitly rather than autoloading a rule for it (skill-only on purpose, to keep the format spec out of the always-on context window).
Commit message and PR title format guidance lives in the [`qv-devops-pr-create`](../../skills/qv-devops-pr-create/SKILL.md) skill — invoke it explicitly rather than autoloading a rule for it (skill-only on purpose, to keep the format spec out of the always-on context window).

## Quick rules — surface-level reminders

Expand Down Expand Up @@ -82,4 +82,4 @@ These are the bar; the deep-dive lives in the topic files above.

## Commit messages and PR titles

The full format spec, allowed prefixes, allowed tags, validation regex, and quality guidelines live in the [`devops-pr-create`](../../skills/devops-pr-create/SKILL.md) skill. Invoke `/devops-pr-create` rather than relying on this rule — kept out of the auto-load context window on purpose.
The full format spec, allowed prefixes, allowed tags, validation regex, and quality guidelines live in the [`qv-devops-pr-create`](../../skills/qv-devops-pr-create/SKILL.md) skill. Invoke `/qv-devops-pr-create` rather than relying on this rule — kept out of the auto-load context window on purpose.
2 changes: 1 addition & 1 deletion .cursor/rules/registry-server/main.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -73,4 +73,4 @@ Use `lib/logger.js`. Avoid logging sensitive information (keys, tokens).

### Autobase + HyperDB Multi-Writer Patterns

When working with Autobase, HyperDB, multi-writer patterns, or peer discovery, use the `registry-autobase-patterns` skill.
When working with Autobase, HyperDB, multi-writer patterns, or peer discovery, use the `qv-registry-autobase-patterns` skill.
2 changes: 1 addition & 1 deletion .cursor/rules/sdk/docs-freshness.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ This rule monitors two packages that have dedicated knowledge-base documentation

| Source area | Documentation |
|---|---|
| `lib/registry-service.js`, `scripts/build-db-spec.js`, `shared/spec/` | `.cursor/skills/registry-autobase-patterns/` |
| `lib/registry-service.js`, `scripts/build-db-spec.js`, `shared/spec/` | `.cursor/skills/qv-registry-autobase-patterns/` |

## What to do

Expand Down
10 changes: 6 additions & 4 deletions .cursor/rules/sdk/sdk-pod-packages.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,10 @@ globs:

## Skill Naming Convention

Skills for SDK pod should use the `sdk-` prefix:
Skills for SDK pod should use the `qv-sdk-` prefix:

- `sdk-pr-create`
- `sdk-changelog`
- `sdk-release`
- `qv-sdk-pr-create`
- `qv-sdk-changelog`
- `qv-sdk-backmerge`
- `qv-sdk-e2e-create`
- `qv-sdk-pr-status`
14 changes: 8 additions & 6 deletions .cursor/rules/sdk/skill-authoring-guidelines.mdc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
description: Guidelines for creating SDK pod Cursor skills
alwaysApply: false
globs:
- .cursor/skills/sdk-**
- .cursor/skills/qv-sdk-**
---

# Skill Authoring Guidelines
Expand All @@ -25,10 +25,12 @@ Guidelines for creating effective Cursor skills, based on the [Agent Skills spec

## Naming Convention

**Use pod prefix for skill directories:**
**Use `qv-` prefix plus pod segment for skill directories:**

- SDK pod skills: `sdk-pr-create`, `sdk-changelog`, `sdk-release`
- Other pods: `infra-deploy`, `platform-migration`
- SDK pod skills: `qv-sdk-pr-create`, `qv-sdk-changelog`, `qv-sdk-backmerge`
- DevOps pod: `qv-devops-pr-create`, `qv-devops-pr-review`
- Addon pod: `qv-addon-changelog`, `qv-addon-pr-create`
- Cross-pod PR workflow: `qv-pr-review`, `qv-pr-test`, `qv-pr-mine`

**If pod is unclear, ask the user.**

Expand All @@ -42,7 +44,7 @@ Guidelines for creating effective Cursor skills, based on the [Agent Skills spec

**Prefer gerund form or action-oriented names:**

- Good: `processing-pdfs`, `analyzing-data`, `sdk-pr-create`
- Good: `processing-pdfs`, `analyzing-data`, `qv-sdk-pr-create`
- Avoid: `helper`, `utils`, `tools`

## Required Frontmatter
Expand Down Expand Up @@ -328,7 +330,7 @@ Choose one term and use it throughout:

### Vague Skill Names

- Good: `sdk-pr-create`, `processing-pdfs`
- Good: `qv-sdk-pr-create`, `processing-pdfs`
- Bad: `helper`, `utils`, `stuff`

## Degrees of Freedom
Expand Down
26 changes: 13 additions & 13 deletions .cursor/skills/_lib/pr-skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Cross-cutting daily workflow helpers live next door in

This directory does not contain a `SKILL.md`; it is not a Cursor skill itself. The user-facing skills live under `.cursor/skills/`:

- `pr-review/` — generic single-PR review. Pod-agnostic.
- `pr-test/` — generic single-PR local validation. Pod-agnostic.
- `pr-mine/` — cross-pod "my open PRs" dashboard. Discovers every pod under `.github/teams/` and routes per-PR ping logic to the owning pod.
- `qv-pr-review/` — generic single-PR review. Pod-agnostic.
- `qv-pr-test/` — generic single-PR local validation. Pod-agnostic.
- `qv-pr-mine/` — cross-pod "my open PRs" dashboard. Discovers every pod under `.github/teams/` and routes per-PR ping logic to the owning pod.
- `<pod>-pr-status/` — per-pod team dashboard, thin wrapper invoking the shared script with `--pod <name> --mode team`.

## Files
Expand All @@ -17,19 +17,19 @@ This directory does not contain a `SKILL.md`; it is not a Cursor skill itself. T
- [`pr-activity.mjs`](pr-activity.mjs) — shared PR data collector/classifier used by `pr-status.mjs` and daily workflow tooling. It fetches open PRs, resolves pod ownership, computes review state, stale/re-review/ready groups, and merge-conflict flags.
- [`team.mjs`](team.mjs) — team-metadata loader. `loadTeam(pod)` reads a single pod; `discoverPods()` enumerates every `.github/teams/<pod>.json`; `findPodForFiles(files, pods)` returns the pod that owns a PR's touched files (first match wins).
- [`slack.mjs`](slack.mjs) — Slack-handle map loader. File lives at `~/.config/qvac-pr-skills/slack.json`, schema `{ map, pendingReview }`. Bootstraps missing entries from `gh api users/<login>` and parks newly seeded logins on `pendingReview` so the skill workflow can confirm them with the user.
- [`worktree.mjs`](worktree.mjs) — worktree manager for `/pr-review` and `/pr-test`. `resolvePR` (gh-resolved baseRefName, fail-fast — does NOT default to main), `fetchPRRefs` (single fetch for both PR head and base ref), `ensureWorktreeSynced` (sync mode, in-place `reset --hard`; preserves untracked artifacts at the same SHA and runs `clean -fdx` only after SHA drift), `lockPR` (per-PR flock), `computePatch` (3-dot diff to `/tmp/pr-<num>.patch`), `cleanupCache` (LRU keep 3).
- [`worktree-prepare.mjs`](worktree-prepare.mjs) — CLI entry for `/pr-review`'s worktree mode. Success: prints `WORKTREE_PATH`, `HEAD_SHA`, `PATCH_PATH`, `BASE_REF` on stdout. Any failure: prints `WORKTREE_FALLBACK=<reason>` on stderr and exits 0 so the agent transparently falls back to API-only mode.
- [`pr-test-discover.mjs`](pr-test-discover.mjs) — discovery CLI for `/pr-test`. Orchestrates PR metadata/patch loading, package discovery, and JSON manifest output. It never uses `git diff`/`git status` against the worktree for classification.
- [`worktree.mjs`](worktree.mjs) — worktree manager for `/qv-pr-review` and `/qv-pr-test`. `resolvePR` (gh-resolved baseRefName, fail-fast — does NOT default to main), `fetchPRRefs` (single fetch for both PR head and base ref), `ensureWorktreeSynced` (sync mode, in-place `reset --hard`; preserves untracked artifacts at the same SHA and runs `clean -fdx` only after SHA drift), `lockPR` (per-PR flock), `computePatch` (3-dot diff to `/tmp/pr-<num>.patch`), `cleanupCache` (LRU keep 3).
- [`worktree-prepare.mjs`](worktree-prepare.mjs) — CLI entry for `/qv-pr-review`'s worktree mode. Success: prints `WORKTREE_PATH`, `HEAD_SHA`, `PATCH_PATH`, `BASE_REF` on stdout. Any failure: prints `WORKTREE_FALLBACK=<reason>` on stderr and exits 0 so the agent transparently falls back to API-only mode.
- [`pr-test-discover.mjs`](pr-test-discover.mjs) — discovery CLI for `/qv-pr-test`. Orchestrates PR metadata/patch loading, package discovery, and JSON manifest output. It never uses `git diff`/`git status` against the worktree for classification.
- [`pr-test-generic.mjs`](pr-test-generic.mjs) — package-agnostic discovery helpers: PR JSON/patch loading, patch-status parsing, package path detection, package.json script discovery, generic package classification, and non-SDK recommendation logic.
- [`pr-test-sdk.mjs`](pr-test-sdk.mjs) — SDK-specific `/pr-test` heuristics: SDK pod package detection, SDK example command generation, related SDK examples, related `tests-qvac` filters, and SDK e2e setup recommendations.
- [`pr-test-sdk.mjs`](pr-test-sdk.mjs) — SDK-specific `/qv-pr-test` heuristics: SDK pod package detection, SDK example command generation, related SDK examples, related `tests-qvac` filters, and SDK e2e setup recommendations.

## Modes

| Mode | Pod scope | What it shows | Used by |
|---|---|---|---|
| `team` | required (`--pod`) | All open PRs touching the pod's `ownedPaths` that still need reviews. Three sections: needs-your-re-review, stale (>3d), needs-review. PRs with `mergeable: CONFLICTING` are flagged with `⚠️ MERGE CONFLICTS!`. Pass `--authors pod` to additionally scope the dashboard to PRs authored by pod-roster members; non-roster authors touching pod paths are surfaced in a separate "Excluded" section. | `<pod>-pr-status` |
| `review` | required (`--pod`) | The current user's personal review queue: PRs needing their first review, plus PRs where their review was dismissed. | (currently unused; available for a future skill) |
| `my` | optional (`--pod`); cross-pod by default | The current user's own open PRs grouped by merge readiness. Per-PR pod resolution drives ping logic. Emits copy-paste Slack ping messages for missing reviewers. | `pr-mine` |
| `my` | optional (`--pod`); cross-pod by default | The current user's own open PRs grouped by merge readiness. Per-PR pod resolution drives ping logic. Emits copy-paste Slack ping messages for missing reviewers. | `qv-pr-mine` |

## CLI

Expand Down Expand Up @@ -75,11 +75,11 @@ from the local `upstream` remote.

`ownedPaths` are prefix-matched against changed-file paths to decide whether a PR is "owned" by this pod. Use trailing slashes.

2. Create the per-pod dashboard skill by copying `.cursor/skills/sdk-pr-status/` to `.cursor/skills/<pod>-pr-status/`. Inside the copy, update the SKILL.md frontmatter (`name:`, `description:`) and the script invocation in the `## Usage` block to swap `--pod sdk` for `--pod <pod>`. No other changes required.
2. Create the per-pod dashboard skill by copying `.cursor/skills/qv-sdk-pr-status/` to `.cursor/skills/qv-<pod>-pr-status/`. Inside the copy, update the SKILL.md frontmatter (`name:`, `description:`) and the script invocation in the `## Usage` block to swap `--pod sdk` for `--pod <pod>`. No other changes required.

3. `pr-mine`, `pr-review`, and `pr-test` are NOT pod-specific and do not need duplication. They live at `.cursor/skills/pr-mine/`, `.cursor/skills/pr-review/`, and `.cursor/skills/pr-test/` and discover the new pod automatically.
3. `qv-pr-mine`, `qv-pr-review`, and `qv-pr-test` are NOT pod-specific and do not need duplication. They live at `.cursor/skills/qv-pr-mine/`, `.cursor/skills/qv-pr-review/`, and `.cursor/skills/qv-pr-test/` and discover the new pod automatically.

4. The first time anyone on the new pod runs `/pr-mine`, the shared script auto-fills `~/.config/qvac-pr-skills/slack.json` with `gh api users/<login>` names for the newly added logins and emits `SLACK_VALIDATION_REQUIRED <N>` on stderr, prompting the skill workflow to drive a confirm-or-correct flow with the user.
4. The first time anyone on the new pod runs `/qv-pr-mine`, the shared script auto-fills `~/.config/qvac-pr-skills/slack.json` with `gh api users/<login>` names for the newly added logins and emits `SLACK_VALIDATION_REQUIRED <N>` on stderr, prompting the skill workflow to drive a confirm-or-correct flow with the user.

## Slack-handle map (per-user, never committed)

Expand All @@ -91,7 +91,7 @@ from the local `upstream` remote.
"pendingReview": ["<github-login>"]
}
```
- The script appends to `pendingReview` whenever it auto-fills a new entry. The `pr-mine` SKILL workflow consumes the pending list, presents each entry to the user via `AskQuestion`, applies corrections, and clears `pendingReview` once validation is done.
- The script appends to `pendingReview` whenever it auto-fills a new entry. The `qv-pr-mine` SKILL workflow consumes the pending list, presents each entry to the user via `AskQuestion`, applies corrections, and clears `pendingReview` once validation is done.
- Edit the file directly at any time — the script never overwrites entries already in `map`, only adds new ones.

## Worktree cache (per-user, never committed)
Expand All @@ -100,7 +100,7 @@ from the local `upstream` remote.
- One subdirectory per PR num: `pr-<num>/` (sync mode — single path per PR, kept in sync via `fetch + reset --hard` when SHA advances).
- One lock file per PR num: `pr-<num>.lock`. Held by `worktree-prepare.mjs` for the duration of fetch + sync; released before printing the path. Same-PR concurrent invocations serialize on this lock.
- LRU eviction: only the 3 most recently touched worktrees are retained. Older entries are removed via `git worktree remove --force` + `rm -rf`.
- Used by `/pr-review` (read-only source inspection) and `/pr-test` (package manager/build/test commands inside the isolated cache).
- Used by `/qv-pr-review` (read-only source inspection) and `/qv-pr-test` (package manager/build/test commands inside the isolated cache).
- Dirty handling:
- Same SHA: `reset --hard HEAD` resets tracked-file edits and preserves untracked build/test artifacts (`node_modules`, `dist`, native `build/`, logs).
- SHA drift: `reset --hard refs/pr/<num>/head` followed by `clean -fdx` so artifacts from the old PR head are not reused against the new commit.
Expand Down
4 changes: 2 additions & 2 deletions .cursor/skills/_lib/pr-skills/pr-test-discover.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env node
//
// Discovery helper for /pr-test.
// Discovery helper for /qv-pr-test.
//
// Usage:
// node pr-test-discover.mjs <PR-URL> --worktree <WORKTREE_PATH> \
Expand All @@ -9,7 +9,7 @@
// The file list and per-file status come from committed PR state only:
// `/tmp/pr-<num>.json` (`gh pr view --json files`) plus the patch emitted by
// worktree-prepare.mjs. This helper never uses git diff/status against the
// worktree, which may contain untracked build artifacts from /pr-test.
// worktree, which may contain untracked build artifacts from /qv-pr-test.

import { readFileSync } from "node:fs";
import { dirname, join, relative } from "node:path";
Expand Down
2 changes: 1 addition & 1 deletion .cursor/skills/_lib/pr-skills/team.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ export function loadTeam(pod) {
}

// Discover every pod registered under .github/teams/. Used by cross-pod
// modes (e.g. /pr-mine) where the user's PRs may span multiple pods.
// modes (e.g. /qv-pr-mine) where the user's PRs may span multiple pods.
// Returns an array of team objects (same shape as loadTeam(pod)).
export function discoverPods() {
const dir = teamsDir();
Expand Down
2 changes: 1 addition & 1 deletion .cursor/skills/_lib/pr-skills/worktree-prepare.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env node
//
// CLI entry for the default-on worktree mode of /pr-review.
// CLI entry for the default-on worktree mode of /qv-pr-review.
//
// Usage:
// node worktree-prepare.mjs <PR-URL>
Expand Down
Loading
Loading