@laitszkin/apollo-toolkit 2.11.2 → 2.11.4

package/read-github-issue/tests/test_read_issue.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import unittest
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "read_issue.py"
+SPEC = importlib.util.spec_from_file_location("read_issue", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class ReadIssueTests(unittest.TestCase):
+    def test_build_command_with_repo(self) -> None:
+        args = Namespace(issue="123", repo="owner/repo", comments=False, json=False)
+
+        self.assertEqual(
+            MODULE.build_command(args),
+            [
+                "gh",
+                "issue",
+                "view",
+                "123",
+                "--json",
+                MODULE.ISSUE_FIELDS,
+                "--repo",
+                "owner/repo",
+            ],
+        )
+
+    def test_main_returns_error_when_gh_missing(self) -> None:
+        args = Namespace(issue="123", repo=None, comments=False, json=False)
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "subprocess.run", side_effect=FileNotFoundError
+        ), patch("sys.stderr", new_callable=io.StringIO) as stderr:
+            code = MODULE.main()
+
+        self.assertEqual(code, 1)
+        self.assertIn("not in PATH", stderr.getvalue())
+
+    def test_main_json_output(self) -> None:
+        args = Namespace(issue="123", repo=None, comments=False, json=True)
+        payload = {
+            "number": 123,
+            "title": "Need better retries",
+            "body": "detail",
+            "state": "OPEN",
+            "author": {"login": "octocat"},
+            "labels": [],
+            "assignees": [],
+            "comments": [],
+            "createdAt": "2026-03-24T00:00:00Z",
+            "updatedAt": "2026-03-24T01:00:00Z",
+            "closedAt": None,
+            "url": "https://github.com/owner/repo/issues/123",
+        }
+
+        class Result:
+            stdout = json.dumps(payload)
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "subprocess.run", return_value=Result()
+        ), patch("sys.stdout", new_callable=io.StringIO) as stdout:
+            code = MODULE.main()
+
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(stdout.getvalue()), payload)
+
+    def test_print_summary_includes_comments(self) -> None:
+        issue = {
+            "number": 123,
+            "title": "Need better retries",
+            "body": "detail",
+            "state": "OPEN",
+            "author": {"login": "octocat"},
+            "labels": [{"name": "bug"}],
+            "assignees": [{"login": "alice"}],
+            "comments": [
+                {
+                    "author": {"login": "bob"},
+                    "createdAt": "2026-03-24T02:00:00Z",
+                    "body": "extra context",
+                }
+            ],
+            "createdAt": "2026-03-24T00:00:00Z",
+            "updatedAt": "2026-03-24T01:00:00Z",
+            "closedAt": None,
+            "url": "https://github.com/owner/repo/issues/123",
+        }
+
+        with patch("sys.stdout", new_callable=io.StringIO) as stdout:
+            MODULE.print_summary(issue, include_comments=True)
+
+        output = stdout.getvalue()
+        self.assertIn("#123", output)
+        self.assertIn("bug", output)
+        self.assertIn("extra context", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/ship-github-issue-fix/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ship-github-issue-fix
+description: Resolve a GitHub issue in an existing repository and submit the fix directly to the requested branch without opening a PR or doing release work. Use when users ask to read issue N, implement the fix, decide whether planning artifacts are needed, run the relevant tests, and commit/push the result to `main` or another specified branch.
+---
+
+# Ship GitHub Issue Fix
+
+## Dependencies
+
+- Required: `read-github-issue`, `enhance-existing-features`, and `commit-and-push`.
+- Conditional: `systematic-debug` when the issue is primarily a bug investigation or failing behavior report.
+- Optional: none.
+- Fallback: If any required dependency is unavailable, stop and report which dependency blocked the workflow.
+
+## Standards
+
+- Evidence: Read the remote issue and the real implementation before deciding scope, process, or fixes.
+- Execution: Prefer the repo's existing issue-reading helpers, fall back to raw `gh issue` commands when helpers are missing, use spec planning only when the actual change surface justifies it, and push directly to the user-requested branch when submission is requested.
+- Quality: Treat localized bug fixes and narrow optimizations as direct implementation work unless the explored scope proves they need shared planning; finish tests, spec backfill, docs sync, and `AGENTS.md` sync before handing off submission.
+- Output: Report the issue context, chosen workflow, implemented fix, validation evidence, and commit/push result.
+
+## Overview
+
+Use this skill for the recurring workflow where the user wants one GitHub issue taken from remote context through implementation and direct submission. Keep the workflow tight: fetch the issue faithfully, decide whether specs are necessary from the explored codebase, finish the fix with tests, then submit without PR or release steps.
+
+## Workflow
+
+### 1) Read the issue from the remote source first
+
+- Start with `$read-github-issue`.
+- Verify the current repository matches the intended remote before reading issue content.
+- Prefer bundled issue scripts, but if they are missing or fail in the repository, immediately fall back to raw `gh issue view` / `gh issue list` so issue retrieval does not block the workflow.
+- Read issue body, labels, timestamps, and comments before touching code.
+- Treat user phrases such as `修復 issue 123`, `參考 issue 109 優化`, or `閱讀 issue 100 並提交到 main` as triggers for this skill.
+
+### 2) Explore the codebase and decide whether specs are required
+
+- After reading the issue, inspect the real entrypoints, affected modules, tests, and existing planning files.
+- Run `$enhance-existing-features` to decide whether specs are required from the actual change surface.
+- Default to direct implementation for clearly localized bug fixes, regressions, narrow optimizations, or small workflow corrections, even when the issue wording sounds broad.
+- Require specs when the explored change touches critical money movement, permissions, high-risk concurrency, or multi-module behavior changes that need approval traceability.
+- If specs are created and approved, finish all in-scope tasks and backfill them before submission.
+
+### 3) Implement and validate the fix completely
+
+- Keep the fix minimal and grounded in the actual root cause.
+- Reuse existing patterns instead of adding parallel abstractions.
+- If the issue is a bug or failing behavior report, bring in `$systematic-debug` for reproduction, root-cause verification, and regression coverage.
+- Run the most specific relevant tests first, then expand validation as needed.
+- When issue context exposed prior agent mistakes, add regression or guardrail coverage so the same failure is less likely to recur.
+
+### 4) Submit the fix without PR or release work
+
+- If the user asked to commit or push, hand off to `$commit-and-push`.
+- Preserve the user's explicit branch target; when the user says `push to main`, treat direct push to `main` as the default goal.
+- Before the final commit, ensure any required spec backfill, docs synchronization, and `AGENTS.md` alignment are completed.
+- Do not convert this flow into a PR workflow unless the user explicitly requests a PR.
+- Do not perform version bumps, tags, or GitHub Releases in this skill.
+
+### 5) Report the shipped result
+
+- Summarize the issue number and root cause.
+- State whether specs were used or intentionally skipped.
+- List the key files changed, the tests run, and whether commit/push succeeded.
+- Call out any remaining blocker only when one truly prevents completion.

package/ship-github-issue-fix/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ship GitHub Issue Fix"
+  short_description: "Fix a GitHub issue and push directly"
+  default_prompt: "Use $ship-github-issue-fix to read the target GitHub issue from the current repository, decide whether specs are needed, implement the fix with appropriate tests, synchronize docs and AGENTS when needed, and commit and push directly to the requested branch without PR or release steps."

package/version-release/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Standards
 
 - Evidence: Inspect the active change set and the release range before touching version files, tags, or changelog entries.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
 - Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, and treat the `archive-specs` structure as the release-ready documentation format.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
@@ -91,6 +91,9 @@ Load only when needed:
    - Create the version tag locally after commit.
 11. Push
    - Push commit(s) and the release tag to the current branch before publishing the GitHub release when the hosting platform requires the tag to exist remotely.
+   - Do not overlap `git commit`, `git tag`, `git push`, or release-publish steps; wait for each mutation to finish before starting the next one.
+   - After pushing, verify the remote branch tip matches local `HEAD`, and verify the release tag exists remotely via `git ls-remote --tags <remote> <tag>`.
+   - If any git step finishes ambiguously or the remote hashes do not match local state, rerun the missing step sequentially and re-check before publishing the GitHub release.
 12. Publish the GitHub release
    - Create a non-draft GitHub release that matches the pushed version tag.
    - Use the release notes from the new `CHANGELOG.md` entry unless the repository has a stronger established release-note source.

package/fix-github-issues/SKILL.md

@@ -1,105 +0,0 @@
----
-name: fix-github-issues
-description: Resolve issues from remote GitHub repositories via GitHub CLI (`gh`), implement and validate fixes locally, then either open a pull request through `open-source-pr-workflow` (or `open-pr-workflow` in environments that use that alias) or hand off to `commit-and-push` when the user explicitly wants a direct push. Use when users ask to list remote issues, pick one or more issues to fix, and deliver the result through a linked PR or an explicit direct-push workflow.
----
-
-# Fix GitHub Issues
-
-## Dependencies
-
-- Required: `systematic-debug` for diagnosis and validated fixes.
-- Conditional: `open-source-pr-workflow` (or `open-pr-workflow`) when the user wants a PR; `commit-and-push` when the user explicitly wants a direct commit/push flow.
-- Optional: none.
-- Fallback: If the required handoff for the user's requested delivery mode is unavailable, stop and report the blocked dependency instead of improvising another release path.
-
-## Standards
-
-- Evidence: Verify repository context, fetch remote issue details, and derive expected behavior from issue text before coding.
-- Execution: Select the issue, open an isolated worktree by default, fix it through `systematic-debug`, validate locally, then hand off to the delivery workflow that matches the user's request.
-- Quality: Keep scope limited to the selected issue, capture exact validation commands, preserve issue linkage in the final PR or commit message, and treat temporary worktree cleanup as part of completion rather than an optional follow-up.
-- Output: Finish with either a linked PR or a direct pushed commit, then clean up the temporary worktree plus any matching local branch before reporting completion.
-
-## Overview
-
-Use this skill to run an end-to-end issue-fixing loop with `gh`: discover open issues, select a target, implement and test the fix, then hand off either to `open-source-pr-workflow` for PR submission or to `commit-and-push` when the user explicitly wants a direct push.
-
-## Prerequisites
-
-- `gh` is installed and authenticated (`gh auth status`).
-- The current directory is a git repository with the correct `origin`.
-- The repository has test or validation commands that can prove the fix.
-
-## Workflow
-
-### 1) Verify repository and remote context
-
-- Run `gh repo view --json nameWithOwner,isPrivate,defaultBranchRef` to confirm target repo.
-- If the user specifies another repository, always use `--repo <owner>/<repo>` in issue commands.
-- Run `git fetch --all --prune` before implementation.
-
-### 2) List remote issues with GitHub CLI
-
-- Preferred command:
-
-```bash
-python3 scripts/list_issues.py --limit 50 --state open
-```
-
-- Optional filters:
-  - `--repo owner/name`
-  - `--label bug`
-  - `--search "panic in parser"`
-- If the issue target is still unclear, present top candidates and ask the user which issue number to fix.
-
-### 3) Read issue details before coding
-
-- Run `gh issue view <issue-number> --comments` (plus `--repo` when needed).
-- Identify expected behavior, edge cases, and acceptance signals from issue text/comments.
-- Do not guess missing requirements; ask the user when critical details are ambiguous.
-
-### 4) Open worktree by default after issue selection
-
-- Immediately create and enter an isolated worktree once the issue number is selected and confirmed.
-- Use a compliant branch name (`codex/{change_type}/{changes}`) and keep all edits in that worktree.
-- If the user explicitly asks to stay in the current tree, follow that request; otherwise worktree is the default path.
-
-### 5) Implement the fix with `systematic-debug`
-
-- Execute the `systematic-debug` workflow: inspect, reproduce with tests, diagnose, then apply minimal fix.
-- Keep scope limited to the selected issue.
-- Reuse existing code patterns and avoid unrelated refactors.
-
-### 6) Validate the fix
-
-- Run focused tests/lint/build relevant to the touched area.
-- Capture exact commands and outcomes; these will be reused in the PR body.
-- Ensure the change can be linked back to the issue number.
-
-### 7) Open PR via dependency skill
-
-- If the user explicitly asks to commit and push directly, invoke `commit-and-push` instead of opening a PR.
-- In direct-push mode:
-  - keep the issue number in the commit message or final summary when appropriate
-  - state the exact target branch the user requested
-  - push only after validation is complete
-- Otherwise invoke `open-source-pr-workflow` (or `open-pr-workflow` if that alias exists in the environment).
-- In PR mode, provide:
-  - issue number or link
-  - motivation and engineering decisions
-  - executed test commands and results
-- Include issue-closing reference (for example, `Closes #<issue-number>`) whenever a PR is opened.
-
-### 8) Clean up the temporary worktree after PR creation or direct push
-
-- Once the PR is opened or the direct push is complete and no more work is needed in that isolated tree, remove the worktree you created for the fix.
-- Also clean up the matching local branch reference if it is no longer needed locally.
-- Verify the cleanup with `git worktree list` and confirm the temporary path no longer appears before finishing.
-- If the worktree cannot be removed because of uncommitted changes or a still-checked-out branch, resolve that state immediately instead of leaving cleanup for a later user request.
-
-## Included Script
-
-### `scripts/list_issues.py`
-
-- Purpose: consistent remote issue listing via `gh issue list`.
-- Outputs a readable table by default, or JSON with `--output json`.
-- Uses only GitHub CLI so it reflects remote GitHub state.

package/fix-github-issues/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Fix GitHub Issues"
-  short_description: "Resolve remote GitHub issues, then open a PR or push directly"
-  default_prompt: "Use $fix-github-issues to verify the target GitHub repository with gh, list and inspect remote issues, create an isolated worktree and compliant branch after issue selection, use $systematic-debug to reproduce and fix the issue with tests, validate the result, then either hand off to $open-source-pr-workflow for a linked PR or to $commit-and-push when the user explicitly wants a direct push, and finally delete the temporary worktree."