stackrox · davdhacs · Apr 27, 2026
diff --git 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
@@ -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
@@ -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
@@ -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).