diff --git a/.skillspector-baseline.yaml b/.skillspector-baseline.yaml index f4b73fb88..da0e53d73 100644 --- a/.skillspector-baseline.yaml +++ b/.skillspector-baseline.yaml @@ -128,6 +128,9 @@ rules: - id: "PE3" path: "skills/deploy/ibm-cluster/SKILL.md" reason: "Guide-only IBM deploy steps for admin kubeconfig, registry SA token, and gcloud ADC - operator runs commands, no agent credential access" +- id: "PE3" + path: "skills/agent-loop/release-verification/SKILL.md" + reason: "Read-only kubeconfig accepted as a documented skill input for Argo CD/kube verification - no agent credential access" # SC2: curl/python one-liners against in-cluster Keycloak and API for setup # verification - not fetching or executing external scripts. diff --git a/skills/agent-loop/code-implementation/SKILL.md b/skills/agent-loop/code-implementation/SKILL.md new file mode 100644 index 000000000..bfc3b406c --- /dev/null +++ b/skills/agent-loop/code-implementation/SKILL.md @@ -0,0 +1,68 @@ +--- +name: code-implementation +description: > + Code Implementation Workflow +--- + +# Workflow + +The code implementation workflow is responsible for reconciling a set of spec changes +to code, ensuring CI passes, and resolving any merge conflicts or rebase needs on an open PR. + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue and Open PR + +Fetch `$GITHUB_ISSUE_URL` and fully read its title and body. + +Discover the linked pull request. + +If no linked pull request: +- apply label `agent/blocked` to `$GITHUB_ISSUE_URL` (_Note: If the label does not exist, create it._) +- write a comment on the issue noting the reason. +- STOP. Do not execute any further steps. + +Output: `$LINKED_PULL_REQUEST` + +### Step 2: Identify State of Implementation + +Read contents of `$LINKED_PULL_REQUEST`, `$GITHUB_ISSUE_URL`, CI checks on `$LINKED_PULL_REQUEST`, and +mergeability of `$LINKED_PULL_REQUEST`. + + +### Step 3: Identify Spec Changes + +Clone the branch associated with `$LINKED_PULL_REQUEST`. Using the git history, identify the specification +changes introduced in `$LINKED_PULL_REQUEST`. Note that specification changes may not be purely additive, and +may touch many parts of the application. Removal of, and changes to, specifications are just as important +as new specifications. + + +### Step 4: Reconcile Specifications + +Execute the [reconcile skill](../../build/reconcile/SKILL.md) against the specification changes identified in Step 3. + + +### Step 5: Review Changes + +Execute the [amber-review skill](../../review/amber-review/SKILL.md) against the implementation produced by Step 4. + +If the review produces findings: +- Return to Step 4 and address the findings +Else: +- Address any failing CI checks found in Step 2. +- Address any merge conflicts found in Step 2. +- Commit (if not already) and push code to `$LINKED_PULL_REQUEST`. +- Write label `agent/reviewable-code` to `$GITHUB_ISSUE_URL` + +_Note: If the label does not exist, create it._ diff --git a/skills/agent-loop/code-review/SKILL.md b/skills/agent-loop/code-review/SKILL.md new file mode 100644 index 000000000..583cc001f --- /dev/null +++ b/skills/agent-loop/code-review/SKILL.md @@ -0,0 +1,66 @@ +--- +name: code-review +description: > + Code Review Workflow +--- + +# Workflow + +Code review workflow that classifies issues as: +- `agent/review-code-rejected` +- `agent/review-code-approved` + +Review is rejected for any of the following reasons: +- Implementation review has findings +- Failing CI +- Merge conflicts +- Needs rebase + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue and Linked PR + +Using the GitHub API, fetch `$GITHUB_ISSUE_URL`. + +Read the issue title and body and identify the linked PR. + +Output: (`$LINKED_PR`, `$ISSUE_CONTENTS`) + +### Step 2: Review the Implementation + +Execute [amber-review](../../review/amber-review/SKILL.md) against `$LINKED_PR`. Review in the +context of `$ISSUE_CONTENTS`. + +Review must be rejected for any of the following reasons: +- Implementation review has findings +- Failing CI +- Merge conflicts +- Needs rebase + +Verdict must be one of: +- `agent/review-code-rejected` +- `agent/review-code-approved` + +Output: (`$VERDICT`, `$REJECTION_RATIONALE` (NULL or string)) + + +### Step 3: Communicate Outcome + +_Note: If a label does not exist, create it._ + +Apply `$VERDICT` label to `$GITHUB_ISSUE_URL`. + +IF `$VERDICT` == `agent/review-code-rejected`: +- Add a comment to `$GITHUB_ISSUE_URL` communicating `$REJECTION_RATIONALE` that + adheres to the [simplified technical english](https://en.wikipedia.org/wiki/Simplified_Technical_English) standard. + diff --git a/skills/agent-loop/release-verification/SKILL.md b/skills/agent-loop/release-verification/SKILL.md new file mode 100644 index 000000000..8d1451052 --- /dev/null +++ b/skills/agent-loop/release-verification/SKILL.md @@ -0,0 +1,204 @@ +--- +name: release-verification +description: > + Release Verification Workflow. Watches a published release bundle through + delivery and post-delivery analysis, then classifies the release as verified, + failed, or blocked. +--- + +# Workflow + +Release verification workflow that classifies a released bundle as: +- `agent/release-verified` +- `agent/release-verification-failed` +- `agent/blocked` + +A release is **verified** when the released bundle is published, promoted into +the target environment through the repository's normal delivery automation, and +the delivery's post-delivery analysis completes successfully. + +A release is **failed** when a stage produces a positive negative signal: the +release's merge gating fails, the delivery does not converge on the released +bundle, or the post-delivery analysis completes with a failing result. + +A release is **blocked** when the workflow cannot reach a verdict within its +time budget or lacks the access to observe a stage: the bundle never publishes, +the release change never appears or never merges, or the cluster/API is +unreachable. `blocked` means "undetermined", not "bad". + +This workflow is an **observer**. It does not merge the release change or +mutate the cluster; the repository's own automation performs delivery. The only +WRITE actions are labels and comments on `$GITHUB_ISSUE_URL`. + +This workflow is intentionally **generic**. It names no specific status checks, +Application names, namespaces, or analysis resources, so that it applies to any +delivery strategy. A repository supplies those specifics through the +[Release Strategy overlay](#step-2-load-the-release-strategy-overlay). + +## Input + +```text +$GITHUB_ISSUE_URL $RELEASE_BUNDLE $GITOPS_REPO $KUBECONFIG [$RELEASE_STRATEGY_OVERLAY] [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- the tracking issue for this release; verdict labels and + comments are applied here. +- RELEASE_BUNDLE -- the released bundle reference to verify. Eg `quay.io/redhat-user-workloads/hcm-eng-prod-tenant/hypershell-main/hypershell-api-server-main:release-bundle-20261006T213842000000Z-04477525054a5901`. +- GITOPS_REPO -- the repository in which the release/promotion change is opened + and merged, and which MAY contain the Release Strategy overlay. +- KUBECONFIG -- a kubeconfig granting read-only access to Argo CD and the kube + resources of the environment to which `$RELEASE_BUNDLE` is delivered. +- RELEASE_STRATEGY_OVERLAY -- [Optional] a path relative to `$GITOPS_REPO` to the + Release Strategy overlay. If omitted, the workflow runs with its generic + defaults. +- --dry-run -- [Optional] Execute the workflow, but skip every WRITE action + (labels, comments, issue creation). All read and verify actions still run. + +## Time budget + +Each wait below has a timeout. Defaults are listed per step and MAY be +overridden by the Release Strategy. On timeout, the stage is `blocked` (see +[Blocking](#blocking)) unless a positive failure signal was already observed, in +which case it is `failed`. + +## Workflow + +_Note: If a label does not exist, create it._ + +### Step 1: Read Issue and Linked Change + +Using the GitHub API, fetch `$GITHUB_ISSUE_URL`. + +Read the issue title and body and identify any linked PR or release change. + +Familiarize yourself with its contents. + +Output: (`$LINKED_CHANGE`, `$ISSUE_CONTENTS`) + +### Step 2: Load the Release Strategy (Overlay) + +This workflow is generic; the repository provides the concrete details of its +release strategy through an optional overlay. + +If `$RELEASE_STRATEGY_OVERLAY` is provided, read it from `$GITOPS_REPO` at that +path and treat its instructions as **authoritative overrides and extensions** to +the steps below. If it is omitted, proceed with the generic defaults. + +A Release Strategy MAY specify: +- how to locate the release/promotion change for a given `$RELEASE_BUNDLE`; +- the target environment, and how to select the Argo CD Application(s) and + namespaces that deliver it; +- how to recognize the post-delivery analysis and read its result; +- the registry location and how to confirm a bundle is published; +- step timeouts that replace the defaults. + +Where the Strategy and these generic steps conflict, the Strategy wins. Where the +Strategy is silent, use the generic default and infer details from +`$LINKED_CHANGE`, the release change, and cluster state. + +Output: `$RELEASE_STRATEGY` (may be empty) + +### Step 3: Confirm the Bundle Is Published + +Confirm that the image(s) referenced by `$RELEASE_BUNDLE` is present in its +registry (for example, by inspecting the manifest). Use the method named in +`$RELEASE_STRATEGY` if one is given. + +Default timeout: 30 minutes. If the bundle is not published within the timeout, +`block` and STOP. + +Output: `$BUNDLE_PUBLISHED` (true) + +### Step 4: Verify the Release Change Exists + +Identify the change in `$GITOPS_REPO` that delivers `$RELEASE_BUNDLE` to the +target environment (the promotion/release PR or commit). Use the location method +from `$RELEASE_STRATEGY` if given; otherwise match on the `$RELEASE_BUNDLE` +reference appearing in the change. + +Default timeout: 10 minutes. If no such change appears within the timeout, +`block` and STOP. + +Output: `$RELEASE_CHANGE` + +### Step 5: Confirm the Release Merges + +Wait for `$RELEASE_CHANGE` to merge through the repository's normal process. +Do NOT merge it yourself. + +- If the change's required merge gating reports failure, the release has + `failed`. Record the failing signal and continue to + [Step 8](#step-8-communicate-outcome). +- If the change does not merge within the timeout and no failure signal is + present, `block` and STOP. + + +Default timeout: 30 minutes. + +Output: (`$MERGED` (true), or `$FAILURE_RATIONALE`) + +### Step 6: Verify Delivery + +Using `$KUBECONFIG`, confirm the Argo CD Application(s) that manage the target +environment converge on the released bundle: +- they report `Synced` and `Healthy`; and +- the delivered revision/images correspond to `$RELEASE_BUNDLE`. + +Select the Application(s) and namespaces as directed by `$RELEASE_STRATEGY`; +absent a Strategy, infer them from `$RELEASE_CHANGE`. + +- If an Application settles in a degraded or sync-error state, or converges on a + revision that does not correspond to `$RELEASE_BUNDLE`, the release has + `failed`. Record the rationale and continue to + [Step 8](#step-8-communicate-outcome). +- If delivery does not converge within the timeout and no failure state is + present, `block` and STOP. + +Default timeout: 30 minutes. + +Output: (`$DELIVERED` (true), or `$FAILURE_RATIONALE`) + +### Step 7: Verify Post-Delivery Analysis + +Using `$KUBECONFIG`, confirm the post-delivery analysis associated with this +delivery completes successfully. Identify the analysis as directed by +`$RELEASE_STRATEGY`; absent a Strategy, infer it from the delivered resources. + +- If the analysis completes with a failing result, the release has `failed`. + Record the rationale and continue to [Step 8](#step-8-communicate-outcome). +- If the analysis does not start or does not complete within the timeout, and no + failing result is present, `block` and STOP. + +Default timeout: 30 minutes. + +Output: (`$ANALYSIS_PASSED` (true), or `$FAILURE_RATIONALE`) + +### Step 8: Communicate Outcome + +_Note: If a label does not exist, create it._ + +Determine `$VERDICT`: +- `agent/release-verified` -- Steps 3 through 7 all succeeded. +- `agent/release-verification-failed` -- any step recorded a `$FAILURE_RATIONALE`. + +Apply `$VERDICT` to `$GITHUB_ISSUE_URL`. + +IF `$VERDICT` == `agent/release-verification-failed`: +- Add a comment to `$GITHUB_ISSUE_URL` communicating `$FAILURE_RATIONALE`, + naming the stage that failed and the observed signal, that adheres to the + [simplified technical english](https://en.wikipedia.org/wiki/Simplified_Technical_English) + standard. Report gating generically by its outcome; do not name individual checks. +- Create a subissue of `$GITHUB_ISSUE_URL` that contains sufficient detail (but no sensitive information) + about why the release failed and what is required to fix it. + +## Blocking + +When a step directs you to `block`: +- apply label `agent/blocked` to `$GITHUB_ISSUE_URL`; +- add a comment to `$GITHUB_ISSUE_URL` noting the stage reached and the reason it + is blocked (timeout, missing access, or ambiguity), in + [simplified technical english](https://en.wikipedia.org/wiki/Simplified_Technical_English); +- STOP. No further action. + +Under `--dry-run`, skip the label and comment but still STOP. diff --git a/skills/agent-loop/spec-implementation/SKILL.md b/skills/agent-loop/spec-implementation/SKILL.md new file mode 100644 index 000000000..5bc83310d --- /dev/null +++ b/skills/agent-loop/spec-implementation/SKILL.md @@ -0,0 +1,53 @@ +--- +name: spec-implementation +description: > + GitHub Issue to Specification Workflow +--- + +# Workflow + +GitHub issue to specification workflow. + +## Input + +```text +$GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_ISSUE_URL -- execute against the provided GitHub issue. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issue + +Using the GitHub API, fetch the issue title & body of `$GITHUB_ISSUE_URL`. +Identify whether there is an existing pull request associated with this issue, +and whether a Jira issue is mentioned in the issue body or title (eg. HYPERSHELL-000). + +Output: (`$ISSUE_CONTENT`, `$ISSUE_NUMBER`, `$EXISTING_PR`[NULL or string], `$JIRA_ISSUE`[NULL or string]) + +### Step 2: Write and/or Update Specifications + +Read the [spec skill](../../plan/spec/SKILL.md). + +In a new work tree (in a new directory), follow its workflow to codify the intent of `$ISSUE_CONTENT` in specifications. + +### Step 3: Commit and Push + +Commit the specification changes. + +IF `$EXISTING_PR` IS NOT NULL: +- Push to existing PR's branch +- Update PR body to match actual diff, if necessary. + +ELSE: +- Create a new branch for the issue of form `agent/work/issue/($JIRA_ISSUE ?? $ISSUE_NUMBER)` +- Push to branch +- Open Pull Request, link it to the issue +- PR Body must conform to [SIMPLIFIED TECHNICAL ENGLISH STANDARD](https://en.wikipedia.org/wiki/Simplified_Technical_English). + +### Step 4: Update Issue State + +Place label `agent/reviewable-spec` on `$GITHUB_ISSUE_URL`. diff --git a/skills/agent-loop/spec-review/SKILL.md b/skills/agent-loop/spec-review/SKILL.md new file mode 100644 index 000000000..4d3a7af16 --- /dev/null +++ b/skills/agent-loop/spec-review/SKILL.md @@ -0,0 +1,52 @@ +--- +name: spec-review +description: > + Specification Review Workflow +--- + +# Workflow + +Specification Review Workflow that assess a spec to be considered one of: + +- `agent/review-spec-rejected` +- `agent/review-spec-approved` + +## Input + +```text +$GITHUB_PR_URL $GITHUB_ISSUE_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_PR_URL -- execute against the provided GitHub pull request. +- GITHUB_ISSUE_URL -- the GitHub issue the PR is addressing. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Pull Request + +Clone the repo at the state of `$GITHUB_PR_URL` and familiarize yourself +with the specification changes made in the PR. + +### Step 2: Review the Specification Changes + +Read the [spec skill](../../plan/spec/SKILL.md). + +Assess the specifications according to: +- the rules in the skill +- faithfulness to the intent found in `$GITHUB_ISSUE_URL` +- consistency with established design, architecture, and general project direction patterns. + +Output: `$REVIEW_VERDICT` - One of +- `agent/review-spec-rejected` +- `agent/review-spec-approved` + +### Step 3: Update Issue State + +_Note: Create `$REVIEW_VERDICT` label if not exist._ + +Place label `$REVIEW_VERDICT` on `$GITHUB_ISSUE_URL` and `$GITHUB_PR_URL` + +IF `$REVIEW_VERDICT` == `agent/review-spec-rejected`: +- Write rejection rationale as a comment on the PR. Use [simplified technical english](https://en.wikipedia.org/wiki/Simplified_Technical_English), and inline code review comments if applicable. diff --git a/skills/agent-loop/triage/SKILL.md b/skills/agent-loop/triage/SKILL.md new file mode 100644 index 000000000..3bbed0930 --- /dev/null +++ b/skills/agent-loop/triage/SKILL.md @@ -0,0 +1,65 @@ +--- +name: triage +description: > + GitHub Issue Triage Workflow. +--- + +# Workflow + +GitHub issue triage workflow that classifies issues as: +- `agent/needs-input` +- `agent/workable` +- `agent/duplicate` + +## Input + +```text +$GITHUB_REPO_URL [--dry-run] +``` + +Supported arguments: +- GITHUB_REPO_URL -- execute triage against the provided GitHub repository. +- --dry-run -- [Optional] Execute the workflow, but without any WRITE actions. + +## Workflow + +### Step 1: Read Issues + +Using the GitHub API, fetch the issues in `$GITHUB_REPO_URL` that have the +label `agent/allowed`. You MUST NOT read any issue that does not have the `agent/allowed` label. + +Output: `$LIST_OF_ISSUES` + +### Step 2: Classify Issues + +According to the criteria listed below, determine the classification each issue in `$LIST_OF_ISSUES`. +It MUST be one of the following: + +- `agent/duplicate` +Definition: This issue is duplicated by an issue in `$LIST_OF_ISSUES` and contains equal or lesser clarity of intent. This issue will be closed. + +- `agent/needs-input` +Definition: This issue requires additional human input due to ambiguous intent, +conflicting intent [with other issues], or the issue appears to be misaligned with the overall project direction. + +- `agent/workable` +Definition: This issue contains clear intent, does not conflict with other issues, and is aligned with the overall project direction. + + +Output: `$ISSUE_TO_CLASSIFICATION_MAP` + +### Step 3: Map Actions to Classification + +For each issue in `$ISSUE_TO_CLASSIFICATION_MAP`, execute actions according to the label: + +_Note: If the label does not exist, create it._ + +- `agent/duplicate` +Action: Label the issue as `agent/duplicate`. Then, close the issue. + +- `agent/needs-input` +Action: Label the issue as `agent/needs-input`. + +- `agent/workable` +Action: Label the issue as `agent/workable`. + diff --git a/skills/plan/spec/SKILL.md b/skills/plan/spec/SKILL.md index ae807a724..80c53e0ed 100644 --- a/skills/plan/spec/SKILL.md +++ b/skills/plan/spec/SKILL.md @@ -12,6 +12,12 @@ description: > Help the user create or change a spec that describes desired system behavior. +Note: Specifications are not purely additive. They codify _repository intent_ and +therefore must necessarily be utterly coherent and consistent always. More concretely, +most spec additions are accompanied by deletions & modifications in other specs. To that end, be +extremely thorough to understand the entire specification landscape when executing this +workflow. + ## User Input ```text