elastic / elastic/ai-github-actions

[product-manager-impersonator] Quick setup contract manifest for docs sync

Open
#1,695 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
11
Forks
16
Avg merge
22h 9m
Merged PRs (30d)
31

Description

## Feature Idea

**Summary:** Add a `--print-contract` mode to `scripts/quick-setup.sh` that emits canonical quick-setup options and workflow bundles, then use that output as the source for docs snippets.

## Why a Customer Would Want This
Users copy quick-setup commands from docs and expect flags/bundles to work exactly as documented. A generated contract removes ambiguity and prevents setup friction caused by doc/script drift.

## Rough Implementation Sketch
- Add `--print-contract` to `scripts/quick-setup.sh` to output machine-readable metadata (supported flags, default bundle, `--continuous-improvement` bundle, deprecated aliases).
- Add a tiny generator/check script that renders docs snippets from that contract output.
- Use the generated snippet in `gh-agent-workflows/README.md` (and optionally docs pages that restate quick-setup options).
- Fail CI when generated docs are stale relative to script output.

## Why It Won't Be That Hard
The change is localized to one shell script plus lightweight docs-generation/check plumbing. It reuses existing quick-setup data that already lives in arrays and argument parsing logic, so the effort is mostly exposing existing state and wiring a validation step.

## Evidence
- `scripts/quick-setup.sh#L7` still advertises `[--set-secret]` in usage comments.
- `scripts/quick-setup.sh#L33-L57` option parser currently supports only `--repo`, `--branch`, `--workflows`, `--continuous-improvement`, `--dry-run`, `-h/--help`.
- `gh-agent-workflows/README.md#L63-L64` references `--skip-secret`, which is not parsed by the script.
- `scripts/quick-setup.sh#L122-L136` defines continuous-improvement workflow membership in code.
- `docs/workflows/gh-agent-workflows.md#L27` documents a bundle list separately, which can drift from script-defined membership.
- Recent maintenance activity (for example PR `#1680`) shows this repo frequently updates workflow/compiler behavior, increasing value of a single generated source of truth for onboarding docs.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Product Manager Impersonator](https://github.com/elastic/ai-github-actions/actions/runs/30352217833)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Contributor guide

Open the contributing guide

Research direction

Start with scripts/quick-setup.sh, especially its option parser and continuous-improvement workflow definitions, then compare the duplicated details in gh-agent-workflows/README.md and docs/workflows/gh-agent-workflows.md. Define the contract output and generator/check plumbing from the existing script data. Done means the docs use generated snippets and CI detects stale documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, shell
Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.