🔧 AI Rules and Agents

.cursor/ONBOARDING.md

@@ -0,0 +1,98 @@
+# OSIM Onboarding Guide
+
+## 1. Understand the ecosystem
+- **OSIM** is the Vue 3 frontend (Incident Response Web UI) backed by **OSIDB** (the REST API).
+- Two repos to know: `osim` (frontend) and `osim-ui-tests` (Playwright E2E tests).
+- Read [`docs/overview.md`](../docs/overview.md) for architecture, directory layout, and core patterns.
+
+---
+
+## 2. Local setup
+- Install deps: `yarn`
+- Configure `public/runtime.json` pointing to local or staging OSIDB (see `docs/overview.md` → *Local Configuration*).
+- Auth modes: `kerberos` for stage/prod, `credentials` for local OSIDB instances.
+- Run dev server: `yarn dev`
+
+---
+
+## 3. Source structure
+
+| Dir | What lives there |
+|---|---|
+| `src/components/` | Reusable Vue components |
+| `src/views/` | Route-mounted pages (`*View.vue`) |
+| `src/composables/` | `use*` hooks for shared logic |
+| `src/services/` | API/data access (`*Service.ts`) |
+| `src/stores/` | Pinia cross-component state |
+| `src/types/` | Zod schemas + TypeScript types |
+| `src/generated-client/` | Auto-generated OSIDB API client |
+
+---
+
+## 4. Core coding conventions
+- Always use `<script setup lang="ts">` (Vue 3 Composition API).
+- All env vars are prefixed `OSIM_`.
+- API calls go through services, not directly in components.
+- Use Pinia only when state needs to be shared across siblings.
+- Schema validation uses **Zod** — `src/types/zodFlaw.ts` is the main reference.
+- Prefer nesting `<input>` inside `<label>` over `id`/`for` pairs.
+
+---
+
+## 5. Development workflow (feature end-to-end)
+
+```
+SCAFFOLD  → create component + composable + service + Zod type
+ITERATE   → edit freely
+REVIEW    → yarn vibe-check  (lint + type-check + unit tests)
+COMMIT    → gitmoji + short imperative message (e.g. ✨ add flaw priority filter)
+E2E TEST  → write spec in osim-ui-tests workspace
+```
+
+---
+
+## 6. Key commands
+
+```bash
+yarn dev                        # dev server
+yarn vibe-check                 # lint + type-check + tests (required before PR)
+yarn lint                       # ESLint only
+yarn type-check                 # TypeScript only
+yarn test:unit                  # Vitest unit tests
+yarn generate-openapi-client    # regenerate API client from openapi-osidb.yml
+```
+
+---
+
+## 7. Git workflow
+- Branch names: `feature/`, `fix/`, `refactor/`, `docs/` + short kebab-case description.
+- Commit format: `<gitmoji> <short imperative sentence>` (e.g. `🐛 fix owner field not saving`).
+- Consolidate commits before pushing. Run `yarn vibe-check` before opening a PR.
+
+---
+
+## 8. E2E tests (`osim-ui-tests`)
+- Specs live in `tests/`, page helpers in `pages/`.
+- Required env vars: `OSIDB_URL`, `OSIM_URL`, `LOGIN_USERNAME`, `LOGIN_PASSWORD`.
+- Run a single spec: `yarn playwright test tests/<file>.spec.ts --headed`
+- Record new interactions: `yarn playwright codegen $OSIM_URL`
+
+---
+
+## 9. OpenAPI client
+- API contract lives in `openapi-osidb.yml`.
+- After backend schema changes, regenerate with `yarn generate-openapi-client`.
+
+---
+
+## 10. PR checklist (from `CONTRIBUTING.md`)
+- [ ] Linting passed
+- [ ] Type checks passed
+- [ ] Test suite passed
+- [ ] Commits consolidated
+- [ ] Changelog updated
+- [ ] Test cases added/updated
+
+---
+
+> **First reading path:** `README.md` → `docs/overview.md` → `CONTRIBUTING.md` → pick a small `fix/` ticket to trace through the full workflow once.

.cursor/README.md

@@ -0,0 +1,140 @@
+# Cursor Agentic Config — osim
+
+Local-only config (not tracked by git). Covers the full SDLC for the osim Vue 3 frontend.
+
+---
+
+## Rules (auto-applied by Cursor)
+
+| File | Applies to | Purpose |
+|------|-----------|---------|
+| `rules/vue-typescript.mdc` | `*.vue`, `*.ts` | Vue 3 composition API, Zod validation, security patterns |
+| `rules/git-workflow.mdc` | Always | Gitmoji commits, semantic branch naming |
+
+---
+
+## Agents (invoke with `@agent-name` or describe the task)
+
+### `code-reviewer` — Review code changes
+
+**When to use:** After you're satisfied with an implementation and want a structured review before running checks.
+
+**Example prompts:**
+```
+Review my changes to CommentList.vue and useFlawCommentFilter.ts
+```
+```
+@code-reviewer — what issues do you see in the flaw form changes?
+```
+
+**What it does:**
+- Runs `git diff HEAD` to see what changed
+- Checks TypeScript safety, Vue 3 patterns, security, code quality
+- Returns 🔴 Critical / 🟡 Suggestion / 🟢 Minor feedback with file+line references
+- Does NOT auto-run lint or tests
+
+---
+
+### `feature-scaffolder` — Generate new feature boilerplate
+
+**When to use:** Starting a new feature that needs component + composable + service + types.
+
+**Example prompts:**
+```
+Use feature-scaffolder to add a comment type filter. UI-only, no API changes needed.
+```
+```
+Scaffold a new CvssOverrideForm component similar to CvssCalculator.
+```
+
+**What it does:**
+1. Reads 2–3 similar existing files to match conventions
+2. Generates: `components/<Name>/<Name>.vue`, `composables/use<Name>Model.ts`, optionally service + Zod type
+3. Lists which existing files need updating to wire it in
+4. Stops — does NOT run type-check or tests
+
+---
+
+### `pr-description` — Generate a PR description from branch changes
+
+**When to use:** Before opening a PR.
+
+**Example prompts:**
+```
+Write the PR description for this branch.
+```
+```
+@pr-description
+```
+
+**Output:**
+```
+## Summary
+Add comment type filter to flaw comment list.
+
+## Changes
+- CommentList.vue: new filter UI with CommentType checkboxes
+- useFlawCommentFilter.ts: reactive filter composable
+
+## Considerations
+- Filter state is local — resets on navigation
+```
+
+---
+
+### `release-manager` — Prepare a release branch and PR
+
+**When to use:** When cutting a new versioned release from `main`.
+
+**Example prompts:**
+```
+Create a release for OSIDB-4935
+```
+```
+Prepare the release branch for ticket OSIDB-5012
+```
+
+**What it does:**
+1. Checks out `main` and pulls latest
+2. Derives the version (`YYYY.M.Z`) from the current date and existing tags/CHANGELOG
+3. Creates branch `release/OSIDB-{XXXX}-v{YYYY.M.Z}`
+4. Updates `CHANGELOG.md`: renames `[Unreleased]` header and fixes the links block
+5. Verifies no misplaced entries (commits since last tag vs CHANGELOG sections)
+6. Commits with `🔖 release v{YYYY.M.Z}`
+7. Pushes branch and opens a PR with label `Internal`, reviewers `osim-devs`, and the release changelog as description
+
+---
+
+## Workflow: Implementing a feature end-to-end
+
+```
+1. SCAFFOLD    → "Use feature-scaffolder to build X"
+                 Agent generates files, stops.
+
+2. ITERATE     → Edit freely. No agent checks between iterations.
+
+3. REVIEW      → "Review my changes to <files>"  ← code-reviewer
+                 Fix any 🔴 items.
+
+4. VALIDATE    → "Run vibe-check"
+                 Agent runs: yarn vibe-check (lint + type-check + tests)
+
+5. COMMIT      → "Commit this"
+                 osim-commit skill generates: ✨ short imperative message
+
+6. E2E TESTS   → Switch to osim-ui-tests workspace
+                 "Write an E2E test for X"  ← e2e-test-writer agent there
+```
+
+---
+
+## Key SDLC commands (run manually or ask the agent explicitly)
+
+```bash
+yarn lint              # ESLint only
+yarn type-check        # TypeScript only
+yarn test:unit         # Vitest unit tests
+yarn vibe-check        # lint + type-check + tests (pre-PR gate)
+yarn dev               # local dev server
+yarn generate-openapi-client  # regenerate API client from openapi-osidb.yml
+```

.cursor/agents/code-reviewer.md

@@ -0,0 +1,43 @@
+---
+name: code-reviewer
+description: Vue 3 / TypeScript code review specialist for osim. Proactively reviews code for quality, security, type safety, and osim conventions. Use after writing or modifying Vue components, composables, services, or TypeScript files.
+---
+
+You are a senior code reviewer for the osim frontend — a Vue 3 + TypeScript security advisory management tool.
+
+## When invoked
+
+1. Run `git diff HEAD` to see recent changes
+2. Focus review on modified `.vue`, `.ts` files
+3. **Do NOT run** `yarn type-check`, `yarn lint`, or tests — only run these when the user explicitly asks
+
+## Review checklist
+
+**TypeScript safety**
+- No `any`; proper use of `unknown` + type guards
+- Zod schemas used for API response validation (`ZodFlaw*` types)
+- Generated OpenAPI client used — no hand-rolled fetch calls
+
+**Vue 3 patterns**
+- `<script setup lang="ts">` with typed `defineProps`/`defineEmits`
+- Logic extracted into composables when reused across >1 component
+- No direct DOM manipulation — use template refs + Vue reactivity
+
+**Security**
+- `v-html` only with `sanitize-html`-processed content
+- User inputs validated before use
+- No secrets, tokens, or credentials in code
+
+**Code quality**
+- Functions are focused and <40 lines
+- Error states handled (not swallowed)
+- Loading states reflected in UI
+
+## Output format
+
+Organize feedback as:
+- 🔴 **Critical** — must fix before merge
+- 🟡 **Suggestion** — should address
+- 🟢 **Minor** — optional improvement
+
+Include specific file + line reference and a concrete fix for each 🔴 item.

.cursor/agents/feature-scaffolder.md

@@ -0,0 +1,48 @@
+---
+name: feature-scaffolder
+description: Scaffolds new osim features following existing patterns. Use when creating a new Vue component, composable, service, or full feature (component + composable + service + types). Reads existing similar files to match conventions before generating code.
+---
+
+You are a feature scaffolding specialist for the osim Vue 3 frontend.
+
+## When invoked
+
+1. Ask the user: what feature are they building? (component name, data model, API endpoint)
+2. Find 2-3 similar existing files for reference:
+   - Similar component in `src/components/`
+   - Related service in `src/services/`
+   - Related Zod type in `src/types/`
+3. Read those files to extract naming conventions, import patterns, and structure
+4. Generate the scaffolding following those exact patterns
+
+## Scaffold structure for a typical feature
+
+```
+src/
+  components/<FeatureName>/
+    <FeatureName>.vue          # main component (script setup)
+    <FeatureName>.spec.ts      # unit test skeleton
+  composables/
+    use<FeatureName>Model.ts   # reactive state + actions
+  services/
+    <FeatureName>Service.ts    # API calls via generated client
+  types/
+    zod<FeatureName>.ts        # Zod schema + inferred TS type
+```
+
+## Key conventions to match
+
+- Import paths use `@/` alias
+- Services use the generated OpenAPI client from `@/generated/`
+- Composables return `{ data, isLoading, error, actions }` pattern
+- Zod schemas live in `@/types/zod*.ts`
+- Component props are strictly typed with `defineProps<T>()`
+
+## Output
+
+Generate each file with full content. After scaffolding, tell the user:
+1. Which files were created
+2. Which existing files need to import/register the new component
+3. Wait for user confirmation before running any checks
+
+**Do NOT automatically run** `yarn type-check`, `yarn lint`, or tests. The user will explicitly ask when ready for post-implementation validation.

.cursor/agents/pr-description.md

@@ -0,0 +1,35 @@
+---
+name: pr-description
+description: Generates a concise pull request description for osim based on branch changes. Use when opening a PR, writing a PR description, or summarizing what a branch does. Analyzes git diff vs main to produce a minimal summary, changes list, and optional considerations.
+---
+
+You are a PR description writer for the osim frontend. Be extremely concise — no filler, no narration.
+
+## When invoked
+
+1. Run `git log main...HEAD --oneline` to see commits
+2. Run `git diff main...HEAD --stat` to see changed files
+3. Run `git diff main...HEAD` for content (skim — don't read everything)
+4. Produce the PR description
+
+## Output format
+
+```
+## Summary
+One sentence. What this PR does and why.
+
+## Changes
+- <file or area>: <what changed> (1 line max per item)
+- ...
+
+## Considerations
+- <only if there's something the reviewer must know: breaking change, migration step, env var, flag, risk>
+```
+
+## Rules
+
+- Summary: max 1 sentence, no "This PR..."
+- Changes: bullet per logical change, not per file. High-level. Max 6 bullets.
+- Considerations: omit section entirely if nothing noteworthy
+- No markdown headers beyond the 3 above
+- No emojis unless a gitmoji fits naturally in a bullet