diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md deleted file mode 100644 index 8105628..0000000 --- a/.agents/skills/create-github-issue/SKILL.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -name: create-github-issue -description: >- - Create GitHub issues and tickets for this repository using the project issue - body template, duplicate search, and GitHub CLI. Use when the user wants to - file, open, or create a GitHub issue or ticket, or to write a bug report for - this repo. ---- - -# Create GitHub Issue - -File a GitHub issue for this repository using the project ticket body structure. - -Do not create commits or pull requests unless the developer asks. - -## Required Input - -The developer must provide a **short problem or goal** (what should change and why). - -Optional: - -- Extra notes, constraints, or links -- Whether this is a **bug**, **feature**, or **chore** -- A preferred title - -If the problem or goal is missing, ask for it before continuing. - -## Workflow - -Copy this checklist and track progress: - -``` -Issue Progress: -- [ ] Step 1: Confirm input -- [ ] Step 2: Draft the issue -- [ ] Step 3: Search for duplicates and confirm they relate -- [ ] Step 4: Duplicate comment path, or show the draft and wait for approval -- [ ] Step 5: Create the issue or post the comment -- [ ] Step 6: Return the issue URL and number -``` - -### Step 1: Confirm Input - -Confirm you have enough to write a useful ticket: - -- Problem or goal (required) -- Type: bug, feature, or chore (ask if unclear) -- Any extra notes the developer already gave - -Do not invent product requirements. If something is unknown, it belongs under **Open Questions**, not as fake acceptance criteria. - -### Step 2: Draft the Issue - -Write a short, specific **title** (no conventional-commit prefix unless the developer asks). - -Write the **body** using this structure. Keep the headings and order exactly: - -``` -Short description why. - -## Acceptance Criteria - -- at least one criteria -- more are better - -## Open Questions - -- any questions that need to be answered before work can start - -## Out of Scope - -Explain what is out of scope for this issue. - -## Bug details (if this is a bug) - -Fill this subsection only when reporting a bug. Skip it for features and chores. - -### Current behavior - -### Expected behavior - -### Steps to reproduce - -1. -2. -3. - -### Environment - -- OS: -- Node: -- pnpm: -``` - -Rules for filling the template: - -- Open with a short paragraph explaining **why** the work matters. -- **Acceptance Criteria** — concrete, testable bullets. If you cannot name real criteria, put the unknowns under **Open Questions** instead of inventing them. -- **Open Questions** — anything that must be answered before work can start. Use `_None_` if there are none. -- **Out of Scope** — what this issue will not do. Prefer a small, focused ticket (see [AGENTS.md](../../../AGENTS.md)). -- **Bug details** — include this subsection **only** for bugs. Omit the entire `## Bug details` section (and its `###` headings) for features and chores. -- Do not include secrets, tokens, or `.env` values. Never read `.env*` files. -- Do not attach labels unless the developer asks for specific ones. - -### Step 3: Search for Duplicates - -Search existing issues **before** creating. Run from the repository root: - -```bash -.agents/skills/create-github-issue/scripts/search-github-issues.sh -``` - -Examples: - -```bash -.agents/skills/create-github-issue/scripts/search-github-issues.sh issue template -.agents/skills/create-github-issue/scripts/search-github-issues.sh timeout member role -``` - -Use a few distinctive words from the title and problem statement. If the first query is too broad or too narrow, search again with a tighter query. - -**Show the search results first** (including “none found”). Do not show the new-issue draft yet. Ask the developer to confirm whether any result is the same work they wanted to file. - -If they confirm a related existing issue: - -- **Do not create a new issue.** -- **Do not edit** that issue (title, body, labels, or other fields). Contributors cannot update the duplicate this way. -- They **may leave a comment** with more information. -- Use **AskQuestion** (when available; otherwise ask conversationally) with a prompt like: “Add a comment with more information to #?” Options: **Yes — add a comment**, **No — stop**. -- If several results might match, confirm **which issue number** first, then AskQuestion about commenting on that issue. - -If no result relates, or none were found, continue to Step 4 (new-issue draft). - -If the script fails: - -- **`gh` not installed** — tell the developer to install the [GitHub CLI](https://cli.github.com/). -- **Not authenticated** — tell the developer to run `gh auth login`. -- **Wrong repository** — run from the `webdev-bot` clone (`r-webdev/webdev-bot`). - -### Step 4: Duplicate Comment Path, or Show the Draft and Wait for Approval - -**If Step 3 confirmed a duplicate and they chose to comment:** - -Draft a comment from the extra information they wanted on the new ticket. Show the comment text and wait for approval. If they request edits, update it and show it again. - -**If there is no duplicate (or results were unrelated):** - -Show the developer: - -- Proposed **title** -- Proposed **body** (full markdown) - -**Do not create the issue** until they approve the draft, unless they already said to create it (for example “file this issue” or “create it”). - -If they request edits, update the draft and show it again. - -### Step 5: Create the Issue or Post the Comment - -**Comment on a duplicate** — write the approved comment to a temp file, then run from the repository root: - -```bash -.agents/skills/create-github-issue/scripts/comment-github-issue.sh \ - --number \ - --body-file "" -``` - -Delete the temp file afterward. - -**Create a new issue** — write the approved body to a temp file, then run from the repository root: - -```bash -.agents/skills/create-github-issue/scripts/create-github-issue.sh \ - --title "" \ - --body-file "" -``` - -Delete the temp file afterward. - -If the script fails, report the error and do not retry blindly. The same `gh` / auth / repo failures as Step 3 apply. - -Do not pass `--label` unless the developer asked for labels. - -### Step 6: Return the Issue URL and Number - -Reply with: - -- Issue number (e.g. `#101`) -- Issue URL -- Whether this was a **new issue** or a **comment** on an existing issue - -After a **new** issue, tell the developer that it needs to be triaged by the code owners. - -Stop there unless the developer asks to plan or implement the issue (see [plan-github-issue](../plan-github-issue/SKILL.md)). - -## Rules - -- Follow [AGENTS.md](../../../AGENTS.md) for repository conventions, scope, and secrets. -- Always create one issue per concern. Create multiple issues for multiple concerns. -- Prefer small scope: do not bundle unrelated chores into the ticket. -- Do not create `.github/ISSUE_TEMPLATE` files as part of filing an issue. -- Never create commits or pull requests for the described issue. -- Never edit an existing issue to “update” a duplicate. Only comment when the developer agrees via AskQuestion. -- After creating a **new** issue, tell the developer that it needs to be triaged by the code owners. diff --git a/.agents/skills/create-github-issue/scripts/comment-github-issue.sh b/.agents/skills/create-github-issue/scripts/comment-github-issue.sh deleted file mode 100755 index 461ce34..0000000 --- a/.agents/skills/create-github-issue/scripts/comment-github-issue.sh +++ /dev/null @@ -1,118 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -EXPECTED_REPO="r-webdev/webdev-bot" -issue_number="" -body_file="" - -usage() { - cat <<'EOF' -Comment on an existing GitHub issue in the current repository using the GitHub CLI. - -Usage: - comment-github-issue.sh --number --body-file - -Arguments: - --number Issue number to comment on - --body-file Path to a file containing the comment body (markdown) - -Examples: - comment-github-issue.sh --number 100 --body-file /tmp/issue-comment.md - -Requires: gh CLI authenticated for this repository (run `gh auth status`). -Must be run from a clone of r-webdev/webdev-bot. -EOF -} - -require_gh() { - if ! command -v gh >/dev/null 2>&1; then - echo "error: gh CLI is not installed. Install it from https://cli.github.com/" >&2 - exit 1 - fi - - if ! gh auth status >/dev/null 2>&1; then - echo "error: gh CLI is not authenticated. Run \`gh auth login\`." >&2 - exit 1 - fi -} - -require_expected_repo() { - local repository - - if ! repository=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null); then - echo "error: could not determine the GitHub repository. Run this from the webdev-bot clone." >&2 - exit 1 - fi - - if [[ "$repository" != "$EXPECTED_REPO" ]]; then - echo "error: expected repository ${EXPECTED_REPO}, got ${repository}" >&2 - echo " Run this script from the webdev-bot repository root." >&2 - exit 1 - fi -} - -if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then - usage - exit 0 -fi - -while [[ $# -gt 0 ]]; do - case "$1" in - --number) - if [[ $# -lt 2 ]]; then - echo "error: --number requires a value" >&2 - exit 1 - fi - issue_number="$2" - shift 2 - ;; - --body-file) - if [[ $# -lt 2 ]]; then - echo "error: --body-file requires a path" >&2 - exit 1 - fi - body_file="$2" - shift 2 - ;; - *) - echo "error: unknown argument: $1" >&2 - usage >&2 - exit 1 - ;; - esac -done - -if [[ -z "$issue_number" ]]; then - echo "error: --number is required" >&2 - usage >&2 - exit 1 -fi - -if [[ ! "$issue_number" =~ ^[0-9]+$ ]]; then - echo "error: --number must be a positive integer" >&2 - exit 1 -fi - -if [[ -z "$body_file" ]]; then - echo "error: --body-file is required" >&2 - usage >&2 - exit 1 -fi - -if [[ ! -f "$body_file" ]]; then - echo "error: body file not found: ${body_file}" >&2 - exit 1 -fi - -if [[ ! -s "$body_file" ]]; then - echo "error: body file is empty: ${body_file}" >&2 - exit 1 -fi - -require_gh -require_expected_repo - -comment_url="$(gh issue comment "$issue_number" --body-file "$body_file")" - -echo "Commented on issue #${issue_number}" -echo "$comment_url" diff --git a/.agents/skills/create-github-issue/scripts/create-github-issue.sh b/.agents/skills/create-github-issue/scripts/create-github-issue.sh deleted file mode 100755 index ef8a541..0000000 --- a/.agents/skills/create-github-issue/scripts/create-github-issue.sh +++ /dev/null @@ -1,114 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -EXPECTED_REPO="r-webdev/webdev-bot" -title="" -body_file="" - -usage() { - cat <<'EOF' -Create a GitHub issue in the current repository using the GitHub CLI. - -Usage: - create-github-issue.sh --title --body-file <path> - -Arguments: - --title Issue title - --body-file Path to a file containing the issue body (markdown) - -Examples: - create-github-issue.sh --title "Add issue template" --body-file /tmp/issue-body.md - -Requires: gh CLI authenticated for this repository (run `gh auth status`). -Must be run from a clone of r-webdev/webdev-bot. -EOF -} - -require_gh() { - if ! command -v gh >/dev/null 2>&1; then - echo "error: gh CLI is not installed. Install it from https://cli.github.com/" >&2 - exit 1 - fi - - if ! gh auth status >/dev/null 2>&1; then - echo "error: gh CLI is not authenticated. Run \`gh auth login\`." >&2 - exit 1 - fi -} - -require_expected_repo() { - local repository - - if ! repository=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null); then - echo "error: could not determine the GitHub repository. Run this from the webdev-bot clone." >&2 - exit 1 - fi - - if [[ "$repository" != "$EXPECTED_REPO" ]]; then - echo "error: expected repository ${EXPECTED_REPO}, got ${repository}" >&2 - echo " Run this script from the webdev-bot repository root." >&2 - exit 1 - fi -} - -if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then - usage - exit 0 -fi - -while [[ $# -gt 0 ]]; do - case "$1" in - --title) - if [[ $# -lt 2 ]]; then - echo "error: --title requires a value" >&2 - exit 1 - fi - title="$2" - shift 2 - ;; - --body-file) - if [[ $# -lt 2 ]]; then - echo "error: --body-file requires a path" >&2 - exit 1 - fi - body_file="$2" - shift 2 - ;; - *) - echo "error: unknown argument: $1" >&2 - usage >&2 - exit 1 - ;; - esac -done - -if [[ -z "$title" ]]; then - echo "error: --title is required" >&2 - usage >&2 - exit 1 -fi - -if [[ -z "$body_file" ]]; then - echo "error: --body-file is required" >&2 - usage >&2 - exit 1 -fi - -if [[ ! -f "$body_file" ]]; then - echo "error: body file not found: $body_file" >&2 - exit 1 -fi - -if [[ ! -s "$body_file" ]]; then - echo "error: body file is empty: $body_file" >&2 - exit 1 -fi - -require_gh -require_expected_repo - -issue_url="$(gh issue create --title "$title" --body-file "$body_file")" -issue_number="${issue_url##*/}" - -echo "Created issue #${issue_number}" -echo "$issue_url" diff --git a/.agents/skills/create-github-issue/scripts/search-github-issues.sh b/.agents/skills/create-github-issue/scripts/search-github-issues.sh deleted file mode 100755 index bb3ca69..0000000 --- a/.agents/skills/create-github-issue/scripts/search-github-issues.sh +++ /dev/null @@ -1,71 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -EXPECTED_REPO="r-webdev/webdev-bot" - -usage() { - cat <<'EOF' -Search GitHub issues in the current repository using the GitHub CLI. - -Usage: - search-github-issues.sh <search-terms...> - -Examples: - search-github-issues.sh issue template - search-github-issues.sh timeout member role - -Requires: gh CLI authenticated for this repository (run `gh auth status`). -Must be run from a clone of r-webdev/webdev-bot. -EOF -} - -require_gh() { - if ! command -v gh >/dev/null 2>&1; then - echo "error: gh CLI is not installed. Install it from https://cli.github.com/" >&2 - exit 1 - fi - - if ! gh auth status >/dev/null 2>&1; then - echo "error: gh CLI is not authenticated. Run \`gh auth login\`." >&2 - exit 1 - fi -} - -require_expected_repo() { - local repository - - if ! repository=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null); then - echo "error: could not determine the GitHub repository. Run this from the webdev-bot clone." >&2 - exit 1 - fi - - if [[ "$repository" != "$EXPECTED_REPO" ]]; then - echo "error: expected repository ${EXPECTED_REPO}, got ${repository}" >&2 - echo " Run this script from the webdev-bot repository root." >&2 - exit 1 - fi -} - -if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then - usage - exit 0 -fi - -if [[ $# -lt 1 ]]; then - usage >&2 - exit 1 -fi - -query="$*" - -require_gh -require_expected_repo - -echo "Repository: ${EXPECTED_REPO}" -echo "Search: ${query}" -echo - -if ! gh issue list --search "$query" --state all --limit 20; then - echo "error: failed to search issues" >&2 - exit 1 -fi diff --git a/AGENTS.md b/AGENTS.md index 4c49e05..701c326 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -219,10 +219,9 @@ pnpm agent-ready claude --skills # .claude/skills -> .agents/skills Agent-specific skill directories are gitignored; `.agents/skills/` is the canonical source committed to the repository. Cursor and Codex also read `.agents/skills/` directly — linking for those agents is optional and the script will ask for confirmation. -| Skill | Use when | -| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| [create-github-issue](.agents/skills/create-github-issue/SKILL.md) | Creating a GitHub issue or ticket (provide a short problem or goal) | -| [plan-github-issue](.agents/skills/plan-github-issue/SKILL.md) | Planning work from a GitHub issue (provide issue number or URL) | +| Skill | Use when | +| -------------------------------------------------------------- | --------------------------------------------------------------- | +| [plan-github-issue](.agents/skills/plan-github-issue/SKILL.md) | Planning work from a GitHub issue (provide issue number or URL) | ## General Guidelines diff --git a/scripts/agent-ready.sh b/scripts/agent-ready.sh index b9550f5..3991777 100755 --- a/scripts/agent-ready.sh +++ b/scripts/agent-ready.sh @@ -207,7 +207,7 @@ check_github_cli() { fi echo "warning: gh is not installed" - echo " Install it for the GitHub-related skills: https://cli.github.com/" + echo " Install it for the plan-github-issue skill: https://cli.github.com/" } link_agent_skills() {