From ab67cdce932c35ce945a31f35e2e25b54c3394de Mon Sep 17 00:00:00 2001 From: davdhacs <105243888+davdhacs@users.noreply.github.com> Date: Mon, 27 Apr 2026 16:55:39 -0600 Subject: [PATCH] Add ACS patch release workflow (thin wrapper) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds patch-release/ directory as an ACP workflow wrapper that loads the patch-release skill from the internal stackrox/skills repo. The wrapper provides: - ambient.json with system prompt (phase model, state detection, decision frameworks, credential handling, error recovery) - /patch-release command that locates/clones the skills repo - CLAUDE.md documenting the architecture The actual procedures, reference data, and scripts live in stackrox/skills (internal) so they work from both ACP and local Claude Code. The workflow is stateless — it detects progress from external signals (git tags, milestones, Jira, Konflux, PRs) so any engineer can pick up a release at any point. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 42 ++++++++++-- patch-release/.ambient/ambient.json | 6 ++ .../.claude/commands/patch-release.md | 24 +++++++ patch-release/CLAUDE.md | 67 +++++++++++++++++++ 4 files changed, 133 insertions(+), 6 deletions(-) create mode 100644 patch-release/.ambient/ambient.json create mode 100644 patch-release/.claude/commands/patch-release.md create mode 100644 patch-release/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md index dc1b45a..63ea049 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,10 +1,21 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with the ACS Triage Workflow. +This file provides guidance to Claude Code (claude.ai/code) when working with ACS workflows. ## Repository Purpose -This is a **single-purpose workflow** for automated triage of StackRox/ACS JIRA issues. It analyzes CI failures, security vulnerabilities, and flaky tests to generate actionable reports with intelligent team assignment. +This repository contains **ACS/StackRox operational workflows** for the Ambient Code Platform (ACP). Each workflow lives in its own directory with its own `.ambient/ambient.json`. + +### Workflows + +| Workflow | Path | Purpose | +|----------|------|---------| +| **ACS Triage** | `.` (root) | Automated triage of JIRA issues with intelligent team assignment | +| **ACS Patch Release** | `patch-release/` | Guided Z-stream (patch) release process, stateless and resumable | + +## ACS Triage Workflow (root) + +Automated triage of StackRox/ACS JIRA issues. Analyzes CI failures, security vulnerabilities, and flaky tests to generate actionable reports with intelligent team assignment. ## Key Features @@ -167,7 +178,26 @@ For questions or issues: --- -**Workflow Type:** Domain-Specific Triage -**Target:** StackRox/ACS JIRA Issues -**Mode:** READ-ONLY (Reports Only) -**Version:** 1.0.0 +## ACS Patch Release Workflow (`patch-release/`) + +Stateless, resumable workflow for ACS Z-stream (patch) releases. Detects progress +from external signals (git tags, milestones, Jira, Konflux) so any engineer can +pick up a release at any point. + +### Commands + +- `/patch-release VERSION` — Perform a patch release (fresh start or resume) + +### Testing in ACP + +1. Push branch to your fork +2. In ACP, select "Custom Workflow..." +3. Enter path: `patch-release` + +See `patch-release/CLAUDE.md` for full documentation. + +--- + +**Workflow Types:** +- ACS Triage (root) — Domain-Specific Triage, READ-ONLY +- ACS Patch Release (`patch-release/`) — Guided Release Process, Stateless + Resumable diff --git a/patch-release/.ambient/ambient.json b/patch-release/.ambient/ambient.json new file mode 100644 index 0000000..36a5e21 --- /dev/null +++ b/patch-release/.ambient/ambient.json @@ -0,0 +1,6 @@ +{ + "name": "ACS Patch Release", + "description": "Guided ACS/StackRox Z-stream (patch) release workflow. Stateless and resumable — inspects git tags, GitHub milestones, Jira, Konflux, and PRs to determine release progress. Any engineer can pick up a release at any point.", + "systemPrompt": "You are an **ACS Patch Release Engineer Assistant** working with a human release engineer to perform ACS Z-stream (patch) releases.\n\n## How This Workflow Works\n\nThis is a thin wrapper. The `/patch-release` command clones the internal `stackrox/skills` repo and loads the patch-release skill. The skill contains all procedures, decision frameworks, and reference data.\n\nYour job: follow the SKILL.md process, read reference files as directed, and apply the conventions (agent executes, engineer decides and acts on external systems).\n\n## ACP-Specific Credential Handling\n\nIn the Ambient Code Platform, credentials work differently than local dev:\n\n### Platform integrations (Settings > Integrations)\n- **Jira** — MCP tools: `mcp__mcp-atlassian__jira_search` and `mcp__mcp-atlassian__jira_get_issue`\n- **GitHub** — `gh` CLI (pre-authenticated)\n\n### Workspace secrets (Settings > Secrets, injected as env vars)\n- **`INFRA_TOKEN`** — infra.rox.systems cluster management (rarely changes)\n- **`OC_TOKEN`** — Konflux/OpenShift access token (refresh daily, ~24h TTL)\n- **`JIRA_EMAIL`** / **`JIRA_TOKEN`** — fallback if Jira MCP not configured\n\nSecrets persist across sessions but changes only take effect in NEW sessions.\n\n### Konflux authentication\nUse `oc login --token=$OC_TOKEN --server=https://api.stone-prd-rh01.pg1f.p1.openshiftapps.com:6443/` (`oc login --web` is not available — no browser in container).\n\n### Token expiry mid-session\n**Never ask the engineer to paste tokens in chat** — sessions are shared and chat history is visible to all editors.\n\nIf `oc` or `infractl` returns 401:\n1. Tell the engineer to update the token in workspace Settings > Secrets\n2. Tell them to stop and restart the session\n3. Reassure them that `/patch-release VERSION` will resume from the current phase", + "startupPrompt": "Greet the engineer and introduce yourself as their ACS Patch Release assistant. Explain that you help perform Z-stream (patch) releases by executing commands, analyzing results, and drafting content while they make decisions and handle credentials.\n\nMention the available command:\n- `/patch-release VERSION` — to perform a patch release (e.g. `/patch-release 4.8.11`)\n\nExplain that the workflow is fully stateless — you detect progress by inspecting git tags, GitHub milestones, Jira, Konflux releases, and PRs. This means any engineer can pick up a release at any point without needing handover notes. The command works the same whether starting fresh or resuming.\n\nAsk the engineer what version(s) they're working on." +} diff --git a/patch-release/.claude/commands/patch-release.md b/patch-release/.claude/commands/patch-release.md new file mode 100644 index 0000000..dd3e169 --- /dev/null +++ b/patch-release/.claude/commands/patch-release.md @@ -0,0 +1,24 @@ +# /patch-release + +Perform an ACS patch release. The version is provided as the argument (e.g. `/patch-release 4.8.11`). + +## Setup + +Locate or clone the patch-release skill from the internal `stackrox/skills` repo: + +```bash +SKILLS_DIR=$(find /tmp ~/dev/stack -maxdepth 2 -name "skills" -type d -exec test -d {}/plugins/patch-release \; -print -quit 2>/dev/null) +if [ -z "$SKILLS_DIR" ]; then + git clone --depth=1 https://github.com/stackrox/skills.git /tmp/skills + SKILLS_DIR=/tmp/skills +fi +PATCH_RELEASE_DIR="${SKILLS_DIR}/plugins/patch-release" +``` + +## Run + +Read `${PATCH_RELEASE_DIR}/skills/patch-release/SKILL.md` and follow its process +with the provided version argument. + +Reference files are at `${PATCH_RELEASE_DIR}/reference/` and scripts at +`${PATCH_RELEASE_DIR}/scripts/`. diff --git a/patch-release/CLAUDE.md b/patch-release/CLAUDE.md new file mode 100644 index 0000000..c607d08 --- /dev/null +++ b/patch-release/CLAUDE.md @@ -0,0 +1,67 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working with the ACS Patch Release workflow. + +## Architecture + +This is a **thin wrapper** around the patch-release skill in `stackrox/skills` (internal repo). + +- **This directory** (`patch-release/`) contains the ACP workflow config (ambient.json), + the command file, and the CLAUDE.md. This is public. +- **`stackrox/skills`** contains the reference data, procedures, lessons learned, and + scripts. This is internal (not public). + +At session start, the `/patch-release` command locates or clones the skills repo +and sets `PATCH_RELEASE_DIR` to point to the plugin's reference data. + +## Workflow Purpose + +Stateless, resumable workflow for ACS Z-stream (patch) releases. Detects progress +from external signals (git tags, GitHub milestones, Jira, Konflux, PRs) so any +engineer can pick up a release at any point. + +## Commands + +- `/patch-release VERSION` — Perform a patch release (e.g. `/patch-release 4.8.11`). + Works for both fresh starts and resuming — detects state automatically. + +## Directory Structure + +``` +patch-release/ # This directory (public, in ambient-workflows) +├── .ambient/ +│ └── ambient.json # Workflow config and system prompt +├── .claude/ +│ └── commands/ +│ └── patch-release.md # Command: clones skills repo, runs workflow +└── CLAUDE.md # This file + +${PATCH_RELEASE_DIR}/ # Located/cloned at runtime (internal, from stackrox/skills) +├── reference/ +│ ├── phase-procedures.md +│ ├── lessons-learned.md +│ ├── advisory-rules.md +│ ├── upgrade-test-procedure.md +│ └── secrets-and-access.md +├── scripts/ +│ └── acs-operator-test.sh +└── skills/patch-release/SKILL.md +``` + +## Critical Constraints + +1. **Never paste tokens in chat** — sessions are shared, use workspace secrets +2. **Never modify Jira** — query only via MCP +3. **Prod release is NOT re-runnable** — escalate on failure +4. **Finish Release defaults to dry-run** — always dry-run first +5. **Jira is source of truth** for advisory content, not git commits + +## Testing in ACP + +1. Push branch to your fork +2. In ACP, select "Custom Workflow..." +3. Enter path: `patch-release` +4. Run `/patch-release X.Y.Z` + +The workflow will clone `stackrox/skills` automatically (requires GitHub +integration configured in Settings > Integrations).