Skip to content
Open
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
177 changes: 177 additions & 0 deletions .agents/skills/assisted-service-verification/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
---
name: assisted-service-verification
description: "MANDATORY: Use this skill BEFORE any git commit, git push, amend, or claiming work is done in the assisted-service repo. Also use when the user asks to test, verify, build, lint, or validate changes. This skill MUST be read and followed before finishing any code change."
---

# Assisted Service Verification

**IMPORTANT: You MUST run at least steps 1-2 of the Quick Verification Checklist below BEFORE committing, amending, or pushing any changes. Do NOT skip verification before git operations.**

## Quick Verification Checklist

For most changes, run these in order (stop at first failure):

```
1. source .venv/bin/activate && skipper make build-minimal # compilation check (ALWAYS use skipper)
2. source .venv/bin/activate && skipper make lint # linters
3. SKIP_UT_DB=1 go test -v ./path/to/changed/package/... # unit tests for changed packages
4. make unit-test # full unit tests (optional, needs Docker/Podman + DB)
```
Comment on lines +14 to +19
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to code block.

The code block should specify bash as the language for proper syntax highlighting and better tool support.

📝 Proposed fix to add language identifier
-```
+```bash
 1. source .venv/bin/activate && skipper make build-minimal   # compilation check (ALWAYS use skipper)
 2. source .venv/bin/activate && skipper make lint             # linters
 3. SKIP_UT_DB=1 go test -v ./path/to/changed/package/...     # unit tests for changed packages
 4. make unit-test                                             # full unit tests (optional, needs Docker/Podman + DB)

</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>

[warning] 14-14: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @.ai/skills/assisted-service-verification/SKILL.md around lines 14 - 19, The
fenced code block in SKILL.md lacks a language identifier; update the
triple-backtick fence to include "bash" (i.e., change tobash) for the
block containing the four commands (lines with "source .venv/bin/activate &&
skipper make build-minimal", "skipper make lint", "SKIP_UT_DB=1 go test -v
./path/to/changed/package/...", and "make unit-test") so tooling and syntax
highlighting recognize it as Bash.


</details>

<!-- fingerprinting:phantom:triton:puma:5021381c-1edb-4397-865d-9a895a9dc0c1 -->

<!-- This is an auto-generated comment by CodeRabbit -->


If generated code was modified (swagger, mocks, CRDs), also run:

```
5. source .venv/bin/activate && skipper make generate # regenerate ALL
6. git diff --exit-code # verify no generated code diff
```
Comment on lines +23 to +26
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to code block.

The code block should specify bash as the language for proper syntax highlighting and better tool support.

📝 Proposed fix to add language identifier
-```
+```bash
 5. source .venv/bin/activate && skipper make generate         # regenerate ALL
 6. git diff --exit-code                                       # verify no generated code diff

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion

🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 23-23: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.ai/skills/assisted-service-verification/SKILL.md around lines 23 - 26,
Update the fenced code block that contains the two commands ("source
.venv/bin/activate && skipper make generate" and "git diff --exit-code") to
specify the language identifier "bash" on the opening triple backticks so the
block becomes a bash code block; locate the code block in SKILL.md containing
those two lines and change the opening fence from ``` to ```bash to enable
proper syntax highlighting and tooling support.


## Critical Rules

- **NEVER run bare `go build`, `go test`, or `go vet` for compilation/lint** — they will fail because Go tooling, C headers (nmstate), and dependencies are only available inside the skipper container.
- **ALWAYS use `skipper make <target>`** for build, lint, and generate targets.
- **`go test` can be run directly** ONLY for unit tests of specific packages that don't need nmstate (see list below). Use `SKIP_UT_DB=1` if a DB container is already running at localhost:5433, or the test framework will try to create one.
- **ALWAYS activate the venv first**: `source .venv/bin/activate` before any `skipper` command.

## Prerequisites

Skipper requires the Python venv:

```bash
source .venv/bin/activate
```

See the `assisted-service-dev-mode` skill for venv setup if `.venv` doesn't exist.

## Build

```bash
source .venv/bin/activate
skipper make build-minimal # build inside skipper container (ALWAYS use this)
```

## Code Generation

### Regenerate mocks only

```bash
skipper run 'go install go.uber.org/mock/mockgen@v0.6.0 && make generate-mocks'
```

Deletes all `mock_*.go` (outside vendor/) then runs `go generate` on all packages. The `mockgen` binary is not pre-installed in the skipper build container, so install it first with `go install` inside the same `skipper run` invocation. Use `skipper run '<commands>'` (not `skipper bash`) for arbitrary commands.

### Regenerate everything

```bash
skipper make generate
```

Runs in order: swagger, go mod tidy/vendor, events, mocks, config, OLM bundle.

### After modifying swagger.yaml

```bash
skipper make generate-from-swagger
```

### After modifying CRD types in api/

```bash
skipper make generate
```

## Linting

```bash
skipper make lint # all linters
skipper make format # auto-format (run before lint to reduce noise)
```

## Testing

### Fast feedback (no database required)

These packages pass without PostgreSQL or nmstate:

```bash
go test -v \
./pkg/app \
./pkg/conversions \
./pkg/error \
./pkg/filemiddleware \
./pkg/jq \
./pkg/kafka \
./pkg/log \
./pkg/mirrorregistries \
./pkg/requestid \
./pkg/s3wrapper \
./pkg/secretdump \
./pkg/thread \
./pkg/validations \
./pkg/webhooks/agentinstall/v1beta1 \
./pkg/webhooks/hiveextension/v1beta1 \
./internal/cluster/validations
```

### Full unit tests (requires Docker/Podman for PostgreSQL)

```bash
make unit-test
```

This starts PostgreSQL at localhost:5433, runs all tests, then stops the DB.

### Manual DB for repeated test runs

```bash
# Terminal 1: keep DB running
make run-db-container

# Terminal 2: run tests repeatedly
SKIP_UT_DB=1 go test -v ./internal/cluster/...
SKIP_UT_DB=1 go test -v ./internal/host/...

# When done
make kill-db-container
```

### Focused tests

```bash
go test -v ./internal/cluster -run TestClusterName # by test name
FOCUS="install_cluster" make run-unit-test # Ginkgo focus
```

## Verify Generated Code (CI Check)

CI runs `verify-generated-code` which does:

1. `make generate` (inside the `assisted-service-generate` container image)
2. `git diff --exit-code` — fails if any generated file differs from what's committed

To reproduce locally:

```bash
skipper make generate
git diff --exit-code
```

**Common causes of failure:**
- Import ordering: `goimports` (run during `generate`) re-sorts imports alphabetically. The `go.uber.org/` prefix sorts *after* `github.com/`, so `go.uber.org/mock/gomock` must appear after all `github.com/` imports within the same import group.
- Stale mocks: If you changed an interface but didn't regenerate mocks.
- Missing `go mod tidy`/`go mod vendor`: If you changed dependencies but didn't re-vendor.

**Always run `skipper make format` after bulk import changes** to let `gci` and `goimports` fix import ordering automatically.

## Dependency Change Verification

After adding, removing, or updating a Go dependency:

```
1. go mod tidy
2. go mod vendor
3. go build ./...
4. skipper make generate # regenerate everything
Comment on lines +169 to +173
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Dependency verification steps contradict the critical execution rules.

Line 172 instructs go build ./..., but Line 30 explicitly says bare go build should not be used. This creates conflicting guidance in the same skill and can break the intended workflow.

Proposed doc fix
-1. go mod tidy
-2. go mod vendor
-3. go build ./...
+1. go mod tidy
+2. go mod vendor
+3. source .venv/bin/activate && skipper make build-minimal
 4. skipper make generate                  # regenerate everything
 5. git diff --exit-code                   # verify no generated code diff
 6. skipper make lint
 7. go test <affected packages>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.ai/skills/assisted-service-verification/SKILL.md around lines 169 - 173,
The steps in SKILL.md conflict: the checklist currently includes "go build
./..." while the doc earlier forbids bare "go build"; update the step to use the
approved verification command instead of "go build ./..." so it aligns with the
rule (e.g., replace the "go build ./..." line with an approved alternative such
as "go list ./..." or the project’s sanctioned build/check command), ensuring
the sequence remains "go mod tidy", "go mod vendor", then the approved
verification command, and finally "skipper make generate".

5. git diff --exit-code # verify no generated code diff
6. skipper make lint
7. go test <affected packages>
```
Comment on lines +169 to +177
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to code block.

The code block should specify bash as the language for proper syntax highlighting and better tool support.

📝 Proposed fix to add language identifier
-```
+```bash
 1. go mod tidy
 2. go mod vendor
 3. go build ./...
 4. skipper make generate                  # regenerate everything
 5. git diff --exit-code                   # verify no generated code diff
 6. skipper make lint
 7. go test <affected packages>

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion

🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 169-169: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.ai/skills/assisted-service-verification/SKILL.md around lines 169 - 177,
The fenced code block containing the shell steps (the block starting with ```
and lines "1. go mod tidy" ... "7. go test <affected packages>") should include
a language identifier; update the opening fence from ``` to ```bash so the block
is ```bash ... ``` to enable proper syntax highlighting and tooling support in
SKILL.md.

129 changes: 129 additions & 0 deletions .agents/skills/mgmt-jira/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
---
name: mgmt-jira
description: "Create and manage JIRA issues in the MGMT project for assisted-service. Use when the user asks to file, create, check, view, or update JIRA issues related to assisted-service development."
---

# MGMT JIRA Issue Management

This skill helps manage JIRA issues in the MGMT (KNI Management) project for assisted-service.

## Project Configuration

- **Project**: MGMT
- **Cloud ID**: 2b9e35e3-6bd3-4cec-b838-f4249ee02432
- **Default Component**: Assisted-Installer (ID: 49033)
- **JIRA URL**: https://redhat.atlassian.net

## Creating Issues

When the user asks to create a JIRA issue:

1. **Determine issue type** (default: Story)
- Story (10009): Feature work, enhancements
- Bug (10016): Problems or errors
- Task (10014): Small discrete work items
- Spike (10104): Research tasks
- Epic (10000): Large stories to be broken down

2. **Use markdown format** for descriptions
- Set `contentFormat: "markdown"` parameter
- Use standard markdown: `##` for headings, backticks for code, `-` for bullets, `|---|---|` for tables
- Do NOT use Jira wiki syntax (`h2.`, `{{code}}`, etc.)

3. **Set default component** to Assisted-Installer unless specified otherwise
- Component ID: 49033
- Pass as: `{"components": [{"id": "49033"}]}`

4. **Return the issue URL** after creation
- Format: https://redhat.atlassian.net/browse/MGMT-XXXXX

### Example: Create issue from markdown file

```typescript
mcp__plugin_atlassian_atlassian__createJiraIssue({
cloudId: "2b9e35e3-6bd3-4cec-b838-f4249ee02432",
projectKey: "MGMT",
issueTypeName: "Story",
summary: "Issue title here",
description: "## Summary\n\n...",
contentFormat: "markdown",
components: [{"id": "49033"}]
})
```

### Available Components

Common assisted-service components:
- **Assisted-Installer** (49033) - Default, general AI work
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sometimes we also use Infrastructure Operator IIRC if it's just operator/controller specific work

- **Assisted-Installer Service** (49094) - Service-specific issues
- **Assisted-Installer Agent** (49081) - Agent-specific issues
- **Assisted-Installer UI (OCM)** (49044) - UI in OCM/SaaS
- **Assisted-Installer CI** (49045) - CI/test infrastructure
- **Assisted-Installer CAPI** (49037) - CAPI integration

## Viewing Issues

To check/view an issue:

```typescript
mcp__plugin_atlassian_atlassian__getJiraIssue({
cloudId: "2b9e35e3-6bd3-4cec-b838-f4249ee02432",
issueIdOrKey: "MGMT-23599"
})
```

## Updating Issues

To update an issue:

```typescript
mcp__plugin_atlassian_atlassian__editJiraIssue({
cloudId: "2b9e35e3-6bd3-4cec-b838-f4249ee02432",
issueIdOrKey: "MGMT-23599",
contentFormat: "markdown",
fields: {
description: "## Updated description...",
components: [{"id": "49033"}]
}
})
```

## Searching Issues

To search for issues:

```typescript
mcp__plugin_atlassian_atlassian__searchJiraIssuesUsingJql({
cloudId: "2b9e35e3-6bd3-4cec-b838-f4249ee02432",
jql: "project = MGMT AND component = 'Assisted-Installer' AND status = 'To Do'"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding the component and status here might be too specific, but just MGMT also might be to broad ... unsure what the best option is, but at the very least I think limiting search to only TODO status by default is probably not great especially since some issue types have different "new" status values.

})
```

## Common Workflows

### 1. File issue from documentation

When user says "create JIRA from docs/dev/issue.md":
1. Read the markdown file
2. Extract title (first heading or filename)
3. Use file content as description
4. Create with default component (Assisted-Installer)
5. Return URL

### 2. Update issue with component

When user says "add Assisted Installer component to MGMT-XXXXX":
1. Use editJiraIssue with `{"components": [{"id": "49033"}]}`
Comment on lines +115 to +116
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use the canonical component name consistently

Line 115 says “Assisted Installer” while the rest of the file uses “Assisted-Installer”. Keep one spelling to prevent copy/paste mistakes in user prompts.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.agents/skills/mgmt-jira/SKILL.md around lines 115 - 116, The string used in
the user prompt "add Assisted Installer component to MGMT-XXXXX" is inconsistent
with the canonical name "Assisted-Installer" used elsewhere; update that prompt
so it reads "add Assisted-Installer component to MGMT-XXXXX" (the line that
shows the editJiraIssue example with {"components": [{"id": "49033"}]}), or
alternatively normalize all occurrences in SKILL.md to "Assisted-Installer" to
avoid copy/paste mistakes.


### 3. Check issue status

When user says "check MGMT-XXXXX":
1. Use getJiraIssue
2. Display: title, status, assignee, description summary

## Important Notes

- **Always use markdown format** (`contentFormat: "markdown"`) for new issues and updates
- **Default to Assisted-Installer component** (49033) unless user specifies otherwise
- **Return the issue URL** after creation so user can view it
- **Use Story type** as default unless context suggests Bug, Task, etc.
1 change: 1 addition & 0 deletions .cursor/skills/assisted-service-dev-mode
1 change: 1 addition & 0 deletions .cursor/skills/assisted-service-verification
1 change: 1 addition & 0 deletions .cursor/skills/mgmt-jira