elastic / elastic/ai-github-actions

[product-manager-impersonator] Quick setup installs a maintainer handoff guide

Open
#1,325 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

## Summary
Add an optional/default handoff guide generated by `scripts/quick-setup.sh` alongside installed trigger files, for example `.github/workflows/ai-github-actions.md`. It would list the workflows installed, the trigger file paths created, links to each per-workflow README/docs page, and the first customization knobs new adopters should review (`additional-instructions`, `setup-commands`, labels/secrets where applicable).

## Why customers want it
Teams adopting GitHub Agent Workflows often have more than one maintainer. The person running quick setup opens the PR, but reviewers and future maintainers only see YAML trigger files after merge. A small generated guide would make the installation self-explaining in the consuming repo and reduce onboarding friction without changing workflow behavior.

## Rough implementation sketch
- Extend `scripts/quick-setup.sh` to build a markdown guide from the resolved `workflows` array after downloading trigger examples.
- Include one row per workflow: installed trigger path, upstream example path, upstream README/docs URL, and a short "review these inputs" note.
- Add the guide path to `created_files` so it is committed in the setup PR; include the equivalent dry-run line.
- Document the generated guide in `README.md` / `gh-agent-workflows/README.md` quick setup sections.

## Why it won't be hard
This is shell string generation using data `quick-setup.sh` already has (`workflows`, `workflow_dir`, `base_url`, `created_files`). No compiler, lock file, permissions, or runtime agent changes are required.

## Evidence
- `README.md:28-41` shows quick setup is the main first-install path and currently describes installing triggers, `agentics-maintenance.yml`, opening a branch/PR, and optional secret setup.
- `scripts/quick-setup.sh:200-219` downloads each selected `gh-agent-workflows//example.yml` to `.github/workflows/trigger-.yml` plus `agentics-maintenance.yml`.
- `scripts/quick-setup.sh:267-278` only commits the created files, opens a PR with `--fill`, and prints `Installed workflows`; it does not persist a consumer-facing handoff document.
- `gh-agent-workflows/README.md:8` states each workflow folder already has an `example.yml` and README covering inputs and safe outputs.
- `gh-agent-workflows/pr-review/README.md:25-38` and `gh-agent-workflows/issue-triage/README.md:25-44` show the per-workflow details that a generated handoff guide could point first-time adopters to.

## Non-duplicate rationale
This is distinct from prior quick-setup ideas such as PR first-run checklist, permission preflight, postflight verifier, workflow chooser, label bootstrap, shared defaults, `--list-workflows`, and existing-file safety. It focuses on a persistent in-repo maintainer handoff guide created during installation.

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

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

Contributor guide

Open the contributing guide

Research direction

Start in scripts/quick-setup.sh, especially the workflow download and created_files sections, and inspect the quick setup documentation in README.md and gh-agent-workflows/README.md. Check the per-workflow README files for the links and customization inputs to include, then exercise the setup dry-run path. Done means the generated guide is committed and its dry-run output, workflow rows, and documentation updates are correct.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, shell
Domain
devops, documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.