diff --git a/.gitignore b/.gitignore index 01f499d..bee8a64 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ __pycache__ -.claude diff --git a/ambient-workflows/workflows/operator-feature-dev/.ambient/ambient.json b/ambient-workflows/workflows/operator-feature-dev/.ambient/ambient.json new file mode 100644 index 0000000..98abbe8 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.ambient/ambient.json @@ -0,0 +1,6 @@ +{ + "name": "Operator Feature Dev", + "description": "Multi-PR OpenShift operator feature development pipeline. Takes an Enhancement Proposal URL and generates a complete implementation across 3 PRs: API type definitions with integration tests, controller/reconciler implementation, and E2E tests.", + "systemPrompt": "You are Atlas, an expert colleague for OpenShift operator feature development from Enhancement Proposals.\n\nAt the start of the session, run the controller skill — it defines the workflow phases, how to execute them, and how to recommend next steps.", + "startupPrompt": "Greet the user as Atlas, their operator feature development assistant. Explain that you guide them through implementing an OpenShift operator feature from an Enhancement Proposal, producing 3 PRs: (1) API type definitions with integration tests, (2) controller/reconciler implementation, (3) E2E tests. Ask them to provide an Enhancement Proposal PR URL and the target operator repository URL to get started." +} diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/SKILL.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/SKILL.md new file mode 120000 index 0000000..eb2943c --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/SKILL.md @@ -0,0 +1 @@ +../../../../../../plugins/oape/skills/effective-go/SKILL.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate-tests.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate-tests.md new file mode 120000 index 0000000..d407c5b --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate-tests.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/api-generate-tests.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate.md new file mode 120000 index 0000000..c3e3366 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-generate.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/api-generate.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-implement.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-implement.md new file mode 120000 index 0000000..0831fe8 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.api-implement.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/api-implement.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.e2e-generate.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.e2e-generate.md new file mode 120000 index 0000000..be126d1 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.e2e-generate.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/e2e-generate.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.init.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.init.md new file mode 120000 index 0000000..3af5d64 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.init.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/init.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.pr.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.pr.md new file mode 100644 index 0000000..ad58536 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.pr.md @@ -0,0 +1,220 @@ +# /oape.pr - Create a draft pull request + +## Purpose + +Submit changes as a draft pull request. Handles authentication, fork workflows, +remote configuration, and cross-repo PR creation. Reusable across all 3 PR +phases (API types, controller, E2E tests). + +## Arguments + +- `$ARGUMENTS`: `` (optional context about which PR phase) + +## Critical Rules + +- **Never push directly to upstream.** Always use a fork remote. +- **Never ask the user for git credentials.** Use `gh auth status` to check. +- **Never skip pre-flight checks.** +- **Always create a draft PR.** +- **Always work in the project repo directory**, not the workflow directory. + +## Process + +### Placeholders + +| Placeholder | Source | Example | +| --- | --- | --- | +| `AUTH_TYPE` | Step 0 | `user-token` / `github-app` / `none` | +| `GH_USER` | Step 0 | `jsmith` | +| `UPSTREAM_OWNER/REPO` | Step 2c | `openshift/cert-manager-operator` | +| `DEFAULT_BRANCH` | Step 2c | `main` | +| `UPSTREAM_REMOTE` | Step 2b | `origin` | +| `FORK_OWNER` | Step 3 | `jsmith` | +| `FORK_REMOTE` | Step 4 | `fork` | +| `BRANCH_NAME` | Step 5 | `feature/ep-1234-api-types` | + +### Step 0: Determine Auth Context + +```bash +gh auth status +``` + +Determine identity: + +```bash +# Normal user tokens: +gh api user --jq .login 2>/dev/null + +# If that fails (403), running as GitHub App/bot: +gh api /installation/repositories --jq '.repositories[0].owner.login' +``` + +Record `GH_USER` and `AUTH_TYPE`: + +- `gh api user` succeeded → `AUTH_TYPE` = `user-token` +- `gh api user` failed but `/installation/repositories` worked → `AUTH_TYPE` = `github-app` +- `gh auth status` failed → try recovering from expired token via git credential + helper, then `gh auth login --with-token`. If recovery fails → `AUTH_TYPE` = `none` + +### Step 1: Locate the Project Repository + +Find the project repo (typically in `/workspace/repos/` or identified from +session context). `cd` into it before proceeding. + +### Step 2: Pre-flight Checks + +**2a. Git configuration:** + +```bash +git config user.name +git config user.email +``` + +If missing, set from `GH_USER`. + +**2b. Inventory remotes:** + +```bash +git remote -v +``` + +**2c. Identify upstream repo and default branch:** + +```bash +gh repo view --json nameWithOwner,defaultBranchRef --jq '{nameWithOwner, defaultBranch: .defaultBranchRef.name}' +``` + +**Do not assume the default branch is `main`.** + +**2d. Check changes:** + +```bash +git status +git diff --stat +``` + +**2e. Pre-flight gate (REQUIRED):** + +Print filled-in placeholder table before proceeding. + +### Step 3: Ensure Fork Exists + +```bash +gh repo list GH_USER --fork --json nameWithOwner,parent --jq '.[] | select(.parent.owner.login == "UPSTREAM_OWNER" and .parent.name == "REPO") | .nameWithOwner' +``` + +If no fork → **HARD STOP**. Ask user to create one at +`https://github.com/UPSTREAM_OWNER/REPO/fork`. Wait for confirmation. + +### Step 4: Configure Fork Remote + +```bash +git remote add fork https://github.com/FORK_OWNER/REPO.git +``` + +**Check fork sync status** — if `.github/workflows/` files differ between fork +and upstream, sync the fork: + +```bash +gh api --method POST repos/FORK_OWNER/REPO/merge-upstream -f branch=DEFAULT_BRANCH +``` + +If sync fails, guide user to sync manually via GitHub UI. + +### Step 5: Create Branch + +Branch naming by PR phase: + +- PR #1: `feature/ep-{number}-api-types-{short-description}` +- PR #2: `feature/ep-{number}-controller-{short-description}` +- PR #3: `feature/ep-{number}-e2e-tests-{short-description}` + +```bash +git checkout -b BRANCH_NAME +``` + +### Step 6: Stage and Commit + +Stage changes selectively, then commit: + +```bash +git commit -m "TYPE(SCOPE): SHORT_DESCRIPTION + +DETAILED_DESCRIPTION + +Ref: openshift/enhancements#EP_NUMBER" +``` + +Commit types by phase: + +- PR #1: `feat(api): add {Kind} type definitions for EP-{number}` +- PR #2: `feat(controller): implement {Kind} reconciler for EP-{number}` +- PR #3: `test(e2e): add E2E tests for {Kind} EP-{number}` + +Include PR description in commit body so GitHub auto-fills the PR form. + +### Step 7: Push to Fork + +```bash +gh auth setup-git +git push -u FORK_REMOTE BRANCH_NAME +``` + +### Step 8: Create Draft PR + +```bash +gh pr create \ + --draft \ + --repo UPSTREAM_OWNER/REPO \ + --head FORK_OWNER:BRANCH_NAME \ + --base DEFAULT_BRANCH \ + --title "TITLE" \ + --body "BODY" +``` + +PR title format: + +- PR #1: `[EP-{number}] API: Add {Kind} type definitions and integration tests` +- PR #2: `[EP-{number}] Controller: Implement {Kind} reconciler` +- PR #3: `[EP-{number}] E2E: Add end-to-end tests for {Kind}` + +PR body should reference: EP URL, what was generated, files changed, review +verdicts, and links to related PRs. + +**If `gh pr create` fails** (403, "Resource not accessible by integration"): + +1. Write PR description to `artifacts/operator-feature-dev/{api|impl|e2e}/pr-description.md` +2. Provide pre-filled GitHub compare URL: + + ```text + https://github.com/UPSTREAM_OWNER/REPO/compare/DEFAULT_BRANCH...FORK_OWNER:BRANCH_NAME?expand=1&title=URL_ENCODED_TITLE&body=URL_ENCODED_BODY + ``` + +3. Provide clone-and-checkout commands for local testing + +### Step 9: Confirm and Report + +Summarize: PR URL (or compare URL), what was included, target branch, +follow-up actions. + +## Fallback Ladder + +1. **Fix and Retry** — diagnose the specific cause and retry +2. **Manual PR via Compare URL** — branch is pushed but `gh pr create` failed +3. **User Creates Fork** — automated forking failed, user creates manually +4. **Patch File** — absolute last resort if all else fails + +## Error Recovery + +| Symptom | Cause | Fix | +| --- | --- | --- | +| `gh auth status` fails | Not logged in | `gh auth login` | +| `git push` permission denied | Pushing to upstream | Switch to fork remote | +| `git push` workflow permission error | Fork out of sync | Sync fork first | +| `gh pr create` 403 | Bot lacks upstream access | Use compare URL | +| Branch not found on remote | Push failed silently | Re-run `git push` | + +## Output + +- PR URL printed to user +- PR description saved to `artifacts/operator-feature-dev/{api|impl|e2e}/pr-description.md` diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.review.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.review.md new file mode 120000 index 0000000..953a20f --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.review.md @@ -0,0 +1 @@ +../../../../../plugins/oape/commands/review.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.speedrun.md b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.speedrun.md new file mode 100644 index 0000000..532b3a0 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/commands/oape.speedrun.md @@ -0,0 +1,188 @@ +# /oape.speedrun - Run all remaining phases without stopping + +## Purpose + +Execute the full operator feature development pipeline autonomously. Detects +which phases are already complete and picks up from the next incomplete one. +Runs all 3 PR deliverables (API types, controller, E2E tests) in sequence +without user interaction between phases. + +## Arguments + +- `$ARGUMENTS`: ` ` (for a fresh start), or + empty (to resume from where you left off) + +Consider the user input before proceeding. It may contain an EP URL, repo URL, +context about where they are in the workflow, or instructions about which +phases to include or skip. + +## How Speedrun Works + +The speedrun loop: + +1. Determine which phase to run next (see "Determine Next Phase" below) +2. If all phases are done (including summary), stop +3. Otherwise, run the command for that phase +4. When the command completes, continue to the next phase + +This loop continues until all phases are complete or an escalation stops you. + +## Determine Next Phase + +Check which phases are already done by looking for artifacts and conversation +context, then pick the first phase that is NOT done. + +### Phase Order and Completion Signals + +| Phase | Command | "Done" signal | +| --- | --- | --- | +| init | `/oape.init` | `artifacts/operator-feature-dev/init-summary.md` exists | +| api-generate | `/oape.api-generate` | `artifacts/operator-feature-dev/api/generation-summary.md` exists | +| api-generate-tests | `/oape.api-generate-tests` | `artifacts/operator-feature-dev/api/test-generation-summary.md` exists | +| api-review | `/oape.review` | `artifacts/operator-feature-dev/api/review-verdict.md` exists | +| api-pr | `/oape.pr` | PR #1 URL has been shared in conversation | +| api-implement | `/oape.api-implement` | `artifacts/operator-feature-dev/impl/implementation-summary.md` exists | +| impl-review | `/oape.review` | `artifacts/operator-feature-dev/impl/review-verdict.md` exists | +| impl-pr | `/oape.pr` | PR #2 URL has been shared in conversation | +| e2e-generate | `/oape.e2e-generate` | `artifacts/operator-feature-dev/e2e/generation-summary.md` exists | +| e2e-review | `/oape.review` | `artifacts/operator-feature-dev/e2e/review-verdict.md` exists | +| e2e-pr | `/oape.pr` | PR #3 URL has been shared in conversation | +| summary | summary skill | `artifacts/operator-feature-dev/summary.md` exists | + +### Rules + +- Check artifacts in order. The first phase whose signal is NOT satisfied is next. +- If no artifacts exist, start at **init**. +- If the user specifies a starting point in `$ARGUMENTS`, respect that. +- If conversation context clearly establishes a phase was completed (even + without an artifact), skip it. + +## Execute a Phase + +1. **Announce** the phase to the user (e.g., "Starting /oape.api-generate — speedrun mode.") +2. **Run** the command for the current phase +3. When the command completes, continue to the next phase + +## Branch Management Between PRs + +After each PR is created, prepare for the next PR deliverable: + +- **After PR #1 (api-pr)**: Create a new branch from the api-types branch for + controller work: `feature/ep-{number}-controller` +- **After PR #2 (impl-pr)**: Create a new branch from the controller branch for + E2E work: `feature/ep-{number}-e2e-tests` + +## Speedrun Rules + +- **Do not stop and wait between phases.** After each phase completes, + continue to the next one. +- **Do not use the controller skill.** This command replaces the controller for + this run. +- **DO still follow CLAUDE.md escalation rules.** If a phase hits an + escalation condition (confidence below 80%, ambiguous EP, multiple valid API + designs with unclear trade-offs, security or compliance concern, architectural + decision needed), stop and ask the user. After the user responds, continue + with the next phase. + +## Phase-Specific Notes + +### init + +- If no EP URL, repo URL, or base branch exists in `$ARGUMENTS` or + conversation, ask the user once, then proceed. +- Present the init summary inline but do not wait for confirmation. + +### api-generate + +- If the EP is ambiguous about API design, this is an escalation point — stop + and ask the user for clarification. + +### api-generate-tests + +- Run `make generate && make manifests` (or `make update`) before this phase + to ensure CRD manifests are up to date. + +### api-review + +- **Verdict: "API types and tests are solid"** — continue to api-pr. +- **Verdict: "tests incomplete"** — attempt to add missing tests, then + continue to api-pr. +- **Verdict: "API design inadequate"** — perform **one** revision cycle: go + back to api-generate → api-generate-tests → api-review. If the second + review still says "inadequate," stop and report the issues to the user. + +### api-pr / impl-pr / e2e-pr + +- Follow the PR command's full process including its fallback ladder. +- If PR creation fails after exhausting fallbacks, report and stop. + +### api-implement + +- If the EP doesn't describe controller behavior clearly, this is an + escalation point — stop and ask. + +### impl-review + +- Same verdict handling as api-review: "solid" → continue, "issues found" → + one revision cycle, then stop if still failing. + +### e2e-generate + +- Uses diff from base branch to generate targeted tests. + +### e2e-review + +- Same verdict handling as other reviews. + +### summary + +- Always run this as the final phase. +- The summary skill scans all artifacts and presents a synthesized overview. +- This is the last thing the user sees. + +## Completion Report (Early Stop Only) + +If you stop early due to escalation (before summary runs), present: + +```markdown +## Speedrun Complete + +### PRs Created +- PR #1 (API Types): [URL or "not created"] +- PR #2 (Controller): [URL or "not created"] +- PR #3 (E2E Tests): [URL or "not created"] + +### Phases Run +- [each phase that ran and its key outcome] + +### Artifacts Created +- [all artifacts with paths] + +### Result +- [PR URLs, or reason for stopping early] + +### Notes +- [any escalations, skipped phases, or items needing follow-up] +``` + +## Usage Examples + +**From the beginning (fresh start):** + +```text +/oape.speedrun https://github.com/openshift/enhancements/pull/1234 https://github.com/openshift/cert-manager-operator main +``` + +**Mid-workflow (some phases already done):** + +```text +/oape.speedrun +``` + +The command detects existing artifacts and picks up from the next incomplete phase. + +**With an explicit starting point:** + +```text +/oape.speedrun Start from /oape.api-implement — I already have the API types +``` diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/skills/controller/SKILL.md b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/controller/SKILL.md new file mode 100644 index 0000000..17077c4 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/controller/SKILL.md @@ -0,0 +1,169 @@ +--- +name: controller +description: Top-level workflow controller that manages phase transitions for operator feature development. +--- + +# Operator Feature Dev Workflow Controller + +You are the workflow controller. Your job is to manage the operator feature +development workflow by executing commands and handling transitions between +phases. The workflow produces 3 Pull Requests from an Enhancement Proposal. + +## WORKSPACE NAVIGATION + +Standard file locations (from workflow root): + +- Config: `.ambient/ambient.json` +- Commands: `.claude/commands/oape.*.md` +- Skills: `.claude/skills/*/SKILL.md` +- Outputs: `artifacts/operator-feature-dev/` + +Tool selection rules: + +- Use Read for: Known paths, standard files, files you just created +- Use Glob for: Discovery (finding multiple files by pattern) +- Use Grep for: Content search + +Never glob for standard files: + +- DO: `Read .ambient/ambient.json` +- DON'T: `Glob **/ambient.json` + +## Phases + +The workflow is grouped into 3 PR deliverables plus a final summary. + +### PR #1: API Type Definitions + +1. **Init** (`/oape.init`) — Clone the operator repo, validate it, detect framework +2. **API Generate** (`/oape.api-generate`) — Generate API type definitions from EP +3. **API Generate Tests** (`/oape.api-generate-tests`) — Generate integration tests +4. **Review** (`/oape.review`) — Review and auto-fix API types and tests +5. **PR** (`/oape.pr`) — Create PR #1 + +### PR #2: Controller Implementation + +6. **API Implement** (`/oape.api-implement`) — Generate controller/reconciler code +7. **Review** (`/oape.review`) — Review and auto-fix controller code +8. **PR** (`/oape.pr`) — Create PR #2 + +### PR #3: E2E Tests + +9. **E2E Generate** (`/oape.e2e-generate`) — Generate E2E test artifacts +10. **Review** (`/oape.review`) — Review and auto-fix E2E tests +11. **PR** (`/oape.pr`) — Create PR #3 + +### Final + +12. **Summary** — Run the `summary` skill to synthesize all artifacts + +## How to Execute a Phase + +1. **Announce** the phase to the user before doing anything else, so the user + knows the workflow is working and learns about the available phases. +2. **Run** the command for the current phase. +3. When the command completes, use "Recommending Next Steps" below to offer + options. +4. Present the command's results and your recommendations to the user. +5. **Use `AskUserQuestion` to get the user's decision.** Present the + recommended next step and alternatives as options. Do NOT continue until the + user responds. This is a hard gate — the `AskUserQuestion` tool triggers + platform notifications and status indicators so the user knows you need + their input. Plain-text questions do not create these signals and the user + may not see them. + +## Recommending Next Steps + +After each phase completes, present the user with **options** — not just one +next step. Use the typical flow as a baseline, but adapt to what actually +happened. + +### Typical Flow + +```text +PR #1: init → api-generate → api-generate-tests → review → pr +PR #2: api-implement → review → pr +PR #3: e2e-generate → review → pr +Final: summary +``` + +### What to Recommend + +After presenting results, consider what just happened, then offer options: + +**Continuing to the next step** — often the next phase in the flow is the best option + +**Skipping forward** — sometimes phases aren't needed: + +- Review says API types are solid → offer `/oape.pr` directly +- The user already has tests → skip `/oape.api-generate-tests` + +**Going back** — sometimes earlier work needs revision: + +- Review finds API types are inadequate → offer `/oape.api-generate` again +- Review finds controller has issues → offer `/oape.api-implement` again +- Build failures after api-implement → offer `/oape.api-implement` to regenerate + +**Between PRs** — after creating a PR, guide the transition: + +- After PR #1 created → recommend starting PR #2 with `/oape.api-implement` +- After PR #2 created → recommend starting PR #3 with `/oape.e2e-generate` +- After PR #3 created → recommend running the summary skill + +**Ending early** — not every EP needs the full pipeline: + +- The user may only want API types (PR #1) and stop +- The user may have their own E2E test process and skip PR #3 + +**Using speedrun** — at any point, offer `/oape.speedrun` to execute all +remaining phases autonomously without stopping + +**Always recommend `/oape.review` before `/oape.pr`.** Do not recommend skipping +review, even for changes that seem straightforward. You generated the code — you +are not in a position to objectively evaluate its quality. Review exists to catch +what the generator misses. Only the user can decide to skip it. + +### How to Present Options + +Lead with your top recommendation, then list alternatives briefly: + +```text +Recommended next step: /oape.review main — review the generated API types. + +Other options: +- /oape.api-generate-tests api/v1alpha1/ — generate tests before review +- /oape.pr main — if you've already reviewed manually +- /oape.speedrun — run all remaining phases autonomously +``` + +## Starting the Workflow + +When the user first provides an EP URL and repo URL: + +1. Execute the **init** phase with `/oape.init ` +2. After init, present results and recommend `/oape.api-generate` + +If the user invokes a specific command (e.g., `/oape.api-implement`), execute +that phase directly — don't force them through earlier phases. + +## Branch Management + +Branches stack so code compiles across PRs: + +- `feature/ep-{number}-api-types` (from base branch) +- `feature/ep-{number}-controller` (from api-types branch) +- `feature/ep-{number}-e2e-tests` (from controller branch) + +After creating PR #1, the controller should guide the user to create a new +branch from the API types branch for PR #2, and so on. + +## Rules + +- **Never auto-advance.** Always use `AskUserQuestion` and wait for the user's + response between phases. This is the single most important rule in this + controller. If you proceed to another phase without the user's explicit + go-ahead, the workflow is broken. +- **Urgency does not bypass process.** The phase-gated workflow exists to + prevent hasty action. Follow every phase gate regardless of perceived urgency. +- **Recommendations come from this file, not from commands.** Commands report + results; this controller decides what to recommend next. diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/skills/effective-go/SKILL.md b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/effective-go/SKILL.md new file mode 120000 index 0000000..eb2943c --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/effective-go/SKILL.md @@ -0,0 +1 @@ +../../../../../../plugins/oape/skills/effective-go/SKILL.md \ No newline at end of file diff --git a/ambient-workflows/workflows/operator-feature-dev/.claude/skills/summary/SKILL.md b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/summary/SKILL.md new file mode 100644 index 0000000..90b8caa --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/.claude/skills/summary/SKILL.md @@ -0,0 +1,144 @@ +--- +name: summary +description: Scan all workflow artifacts and present a synthesized summary of findings, decisions, and status across all 3 PRs. +--- + +# Workflow Summary Skill + +This skill can be invoked at any point in the workflow. It does not require +prior phases to have completed; it summarizes whatever exists so far. + +--- + +You are producing a concise, high-signal summary of everything the operator +feature development workflow has done so far. Your audience is someone who +hasn't been watching the workflow run — they want to know what was generated, +what PRs were created, and what needs attention. + +## Your Role + +Scan the artifact directory, read what's there, and synthesize the important +findings into a single summary. Surface things that might otherwise get buried: +review concerns, convention deviations, EP ambiguities that were resolved, +assumptions made during code generation. + +## Process + +### Step 1: Discover Artifacts + +Scan the artifact root directory to find everything the workflow has produced: + +```bash +find artifacts/operator-feature-dev/ -type f -name '*.md' ! -name 'summary.md' 2>/dev/null | sort +``` + +If `artifacts/operator-feature-dev/` doesn't exist or is empty, report that no +artifacts have been generated yet and stop. + +### Step 2: Read All Artifacts + +Read every artifact file found in Step 1. Don't skip any — even small or +seemingly unimportant files may contain notable findings. + +### Step 3: Extract Key Findings + +As you read each artifact, pull out information in these categories: + +**Enhancement Proposal** + +- EP URL and title +- Key API requirements extracted +- Any ambiguities resolved during generation + +**PR #1: API Type Definitions** + +- API group, version, kind generated +- Types and fields added or modified +- FeatureGate registration (if applicable) +- Integration tests generated and coverage +- Review verdict and any concerns +- PR URL and status + +**PR #2: Controller Implementation** + +- Framework detected (controller-runtime vs library-go) +- Reconciliation workflow implemented +- Dependent resources managed +- RBAC permissions generated +- Review verdict and any concerns +- PR URL and status + +**PR #3: E2E Tests** + +- Test format (Ginkgo vs bash) +- Test coverage (which scenarios) +- Review verdict and any concerns +- PR URL and status + +**Convention Deviations** + +- Any places where the EP conflicted with OpenShift/Kubernetes API conventions +- What was generated instead and why + +**Outstanding Items** + +- Assumptions made without user confirmation +- Review concerns that are still outstanding +- Known limitations or edge cases not covered +- Follow-up work recommended + +### Step 4: Present the Summary + +Present the summary directly to the user using this structure: + +```markdown +## Operator Feature Dev Summary + +**Enhancement Proposal:** [EP URL and title] +**Status:** [where the workflow stopped — e.g., "All 3 PRs created", "PR #1 created, PR #2 in progress"] + +### PRs Created +- PR #1 (API Types): [URL or "not created"] +- PR #2 (Controller): [URL or "not created"] +- PR #3 (E2E Tests): [URL or "not created"] + +### Key Findings +- [The most important things the user should know — 3-5 bullet points max] + +### Decisions Made +- [Any choices made during generation, especially convention deviations or EP ambiguity resolutions] + +### Outstanding Concerns +- [Review caveats, untested edge cases, unconfirmed assumptions — or "None"] + +### Artifacts +- [List of all artifact files with one-line descriptions] +``` + +Keep it tight. The value of this summary is density — if it's as long as the +artifacts themselves, it's not a summary. + +### Step 5: Write the Summary Artifact + +Save the summary to `artifacts/operator-feature-dev/summary.md`. + +## Rules + +- **Read, don't assume.** Base everything on what the artifacts actually say, + not on what you think happened during the workflow. +- **Flag what's missing.** If a phase was skipped or an artifact is absent, + say so. "No E2E tests were generated" is useful information. +- **Don't editorialize.** Report what the artifacts say. If the review flagged + a concern, include it. Don't soften it. +- **Keep it short.** The whole point is that nobody reads the full artifacts. + If your summary is more than ~50 lines of Markdown, cut it down. + +## Output + +- Summary presented directly to the user (inline) +- Summary saved to `artifacts/operator-feature-dev/summary.md` + +## When This Phase Is Done + +The summary is the deliverable. Present it and stop — there is no next phase +to recommend. diff --git a/ambient-workflows/workflows/operator-feature-dev/CLAUDE.md b/ambient-workflows/workflows/operator-feature-dev/CLAUDE.md new file mode 100644 index 0000000..06347ab --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/CLAUDE.md @@ -0,0 +1,71 @@ +# Operator Feature Dev Workflow + +Multi-PR OpenShift operator feature development from Enhancement Proposals: + +1. **Init** (`/oape.init`) — Clone repo, validate operator, detect framework +2. **API Generate** (`/oape.api-generate`) — Generate API type definitions from EP +3. **API Generate Tests** (`/oape.api-generate-tests`) — Generate integration tests for API types +4. **Review** (`/oape.review`) — Review and auto-fix issues +5. **PR** (`/oape.pr`) — Create pull request +6. **API Implement** (`/oape.api-implement`) — Generate controller/reconciler code +7. **E2E Generate** (`/oape.e2e-generate`) — Generate E2E test artifacts +8. **Speedrun** (`/oape.speedrun`) — Run all remaining phases without stopping +9. **Summary** — Synthesize all artifacts into a final status report + +Commands handle atomic operations. The controller skill manages phase +transitions and recommendations. The speedrun command runs all remaining +phases autonomously. Artifacts go in `artifacts/operator-feature-dev/`. + +## Principles + +- Show code, not concepts. Link to `file:line`, not abstract descriptions. +- Derive from conventions, not memory. Fetch and read OpenShift/Kubernetes API conventions on every run. +- Never guess. If the Enhancement Proposal is ambiguous about API details, stop and ask. +- Be thorough and complete: When generating API types, search for all existing types in the package and match style exactly. +- Don't assume tools are missing. Check for version managers (`uv`, `pyenv`, `nvm`) before concluding a runtime isn't available. + +## Hard Limits + +- No direct commits to `main` — always use feature branches +- No token or secret logging — use `len(token)`, redact in logs +- No force-push, hard reset, or destructive git operations +- No modifying security-critical code without human review +- No skipping CI checks (`--no-verify`, `--no-gpg-sign`) +- Never generate code with TODOs — produce production-ready implementations +- Never hardcode operator-specific values — discover from the repository + +## Safety + +- Show your plan with TodoWrite before executing +- Indicate confidence: High (90-100%), Medium (70-89%), Low (<70%) +- Flag risks and assumptions upfront +- Provide rollback instructions for every change + +## Quality + +- Follow the project's existing coding standards and conventions +- Zero tolerance for test failures — fix them, don't skip them +- Conventional commits: `type(scope): description` +- All PRs include EP reference (e.g., `Ref: openshift/enhancements#1234`) + +## Escalation + +Stop and request human guidance when: + +- Enhancement Proposal is ambiguous about API design +- Multiple valid API approaches exist with unclear trade-offs +- Convention-compliant design conflicts with EP requirements +- An architectural decision is required +- The change affects API contracts or introduces breaking changes +- A security or compliance concern arises +- Confidence on the proposed approach is below 80% + +## Working With the Project + +This workflow gets deployed into different operator repos. Respect the target project: + +- Read and follow the project's own `CLAUDE.md` if one exists +- Adopt the project's coding style, not your own preferences +- Match existing controller patterns exactly +- Use the project's existing test framework and patterns +- When in doubt about project conventions, check git history and existing code diff --git a/ambient-workflows/workflows/operator-feature-dev/README.md b/ambient-workflows/workflows/operator-feature-dev/README.md new file mode 100644 index 0000000..1737473 --- /dev/null +++ b/ambient-workflows/workflows/operator-feature-dev/README.md @@ -0,0 +1,127 @@ +# Operator Feature Dev Workflow + +Multi-PR OpenShift operator feature development from Enhancement Proposals. Takes an EP URL and generates a complete implementation across 3 Pull Requests. + +## What It Does + +Given an Enhancement Proposal PR URL and an operator repository URL, this workflow generates: + +1. **PR #1 — API Type Definitions**: Go type definitions with markers, validation, godoc, FeatureGate registration, and `.testsuite.yaml` integration tests +2. **PR #2 — Controller Implementation**: Complete controller/reconciler code with reconciliation logic, dependent resource management, RBAC markers, and status handling +3. **PR #3 — E2E Tests**: End-to-end test artifacts (test cases, execution steps, and Ginkgo/bash test code) based on git diff + +## Directory Structure + +```text +workflows/operator-feature-dev/ +├── .ambient/ +│ └── ambient.json # Workflow configuration +├── .claude/ +│ ├── commands/ # Atomic, argument-driven operations +│ │ ├── oape.init.md # Clone and validate operator repo +│ │ ├── oape.api-generate.md # Generate API types from EP +│ │ ├── oape.api-generate-tests.md # Generate integration tests +│ │ ├── oape.api-implement.md # Generate controller/reconciler +│ │ ├── oape.e2e-generate.md # Generate E2E test artifacts +│ │ ├── oape.review.md # Code review with auto-fix +│ │ ├── oape.pr.md # Create pull request +│ │ └── oape.speedrun.md # Autonomous full pipeline +│ └── skills/ # Orchestration + cross-cutting +│ ├── controller/SKILL.md # Phase transition orchestrator +│ ├── effective-go/SKILL.md # Go best practices +│ └── summary/SKILL.md # Final synthesis +├── CLAUDE.md # Hard limits and safety rules +└── README.md +``` + +## Quick Start + +1. Start the workflow in ACP +2. Provide an Enhancement Proposal PR URL and operator repo URL +3. The controller guides you through each phase, or use `/oape.speedrun` for autonomous execution + +### Example Session + +```text +User: I want to implement EP https://github.com/openshift/enhancements/pull/1234 + in https://github.com/openshift/cert-manager-operator, base branch main + +Atlas: [runs /oape.init, then guides through each phase] +``` + +### Speedrun (Autonomous) + +```text +/oape.speedrun https://github.com/openshift/enhancements/pull/1234 https://github.com/openshift/cert-manager-operator main +``` + +## Commands + +| Command | Arguments | Purpose | +| --- | --- | --- | +| `/oape.init` | ` ` | Clone repo, detect framework | +| `/oape.api-generate` | ` [--design-doc ]` | Generate API type definitions | +| `/oape.api-generate-tests` | `` | Generate integration tests | +| `/oape.api-implement` | ` [--design-doc ]` | Generate controller/reconciler | +| `/oape.e2e-generate` | `` | Generate E2E test artifacts | +| `/oape.review` | `` | Code review with auto-fix | +| `/oape.pr` | `` | Create draft pull request | +| `/oape.speedrun` | ` ` | Run all phases autonomously | + +## Workflow Phases + +```text +PR #1: /oape.init → /oape.api-generate → /oape.api-generate-tests → /oape.review → /oape.pr +PR #2: /oape.api-implement → /oape.review → /oape.pr +PR #3: /oape.e2e-generate → /oape.review → /oape.pr +Final: summary skill +``` + +## Artifacts + +All artifacts are written to `artifacts/operator-feature-dev/`: + +```text +artifacts/operator-feature-dev/ +├── init-summary.md +├── api/ +│ ├── generation-summary.md +│ ├── test-generation-summary.md +│ ├── review-verdict.md +│ └── pr-description.md +├── impl/ +│ ├── implementation-summary.md +│ ├── review-verdict.md +│ └── pr-description.md +├── e2e/ +│ ├── test-cases.md +│ ├── execution-steps.md +│ ├── e2e-suggestions.md +│ ├── generation-summary.md +│ ├── review-verdict.md +│ └── pr-description.md +└── summary.md +``` + +## Prerequisites + +- `git` — Git installed +- `go` — Go toolchain installed +- `gh` — GitHub CLI installed and authenticated +- Access to `openshift/enhancements` repository +- Target operator repository must be a Go-based OpenShift operator + +## Supported Frameworks + +- **controller-runtime** (kubebuilder/operator-sdk) — most common +- **library-go** (OpenShift core operators) — uses SyncFunc pattern + +## Testing + +Use the ACP "Custom Workflow" feature to test without merging: + +| Field | Value | +| --- | --- | +| **URL** | Your fork's git URL | +| **Branch** | Your branch name | +| **Path** | `workflows/operator-feature-dev` |