elastic / elastic/ai-github-actions
[product-manager-impersonator] Quick setup contract manifest for docs sync
- 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
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