@laitszkin/apollo-toolkit 2.11.1 → 2.11.3

package/commit-and-push/SKILL.md

@@ -15,9 +15,9 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply.
-- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, then commit and push without release steps.
-- Quality: Re-run relevant validation for runtime changes and keep project docs plus agent constraints synchronized before committing; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
-- Output: Produce a concise Conventional Commit and push it to the current branch only.
+- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps.
+- Quality: Re-run relevant validation for runtime changes, keep project docs plus agent constraints synchronized before committing, and preserve unrelated local work safely when branch switching or post-push local sync is required; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
+- Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
 ## Overview
 
@@ -43,29 +43,36 @@ Load only when needed:
    - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` have been updated to reflect the actual outcome of the work, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
    - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
    - Treat a spec set as still active when it documents remaining implementation gaps, follow-up integration work, undecided design work, or deferred tasks that still belong to the same in-flight change.
-3. Run code-affecting dependency skills (when applicable)
+3. Resolve branch target before mutating history
+   - Treat an explicit user-specified destination such as `main`, `origin/main`, or another named branch as authoritative over the current branch.
+   - If the current branch does not match the requested destination, inspect `git status --short` for unrelated local changes before switching branches.
+   - Preserve unrelated uncommitted work safely before branch operations, for example with `git stash push`, and restore it after the target branch has been updated.
+   - If the fix was committed on the wrong branch, move it to the requested branch with safe history-preserving operations such as `cherry-pick`, `merge --ff-only`, or a clean replay; do not force-push unless the user explicitly asks for it.
+   - If the user asks to sync the local target branch after pushing, fast-forward or pull that branch locally and then restore any preserved worktree changes.
+4. Run code-affecting dependency skills (when applicable)
    - Run `review-change-set`, `discover-edge-cases`, and `harden-app-security` for the same code-affecting scope when their coverage is needed.
    - Consolidate and resolve all confirmed findings before continuing.
    - Re-run relevant tests when runtime logic changes.
-4. Standardize project docs when specs or doc normalization is needed
+5. Standardize project docs when specs or doc normalization is needed
    - During submission, execute `archive-specs` when `repo-specs-ready-for-conversion` is true or when `project-doc-structure-mismatch` is true.
    - Let `archive-specs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
    - Let the skill normalize any existing project docs to the same structure and archive superseded source spec files.
    - Do not treat unchecked task or decision checkboxes alone as blocking unfinished work; read the surrounding notes and requirement status semantically.
    - If the docs still show unresolved implementation scope that is neither completed, intentionally deferred, nor explicitly `N/A`, do not convert them yet; report that the spec files remain active and should not be deleted.
    - If the current change intentionally ships a partial phase while the same plan set still tracks remaining work, keep that plan set live and skip archival for that scope.
-5. Run pre-commit sync dependencies
+6. Run pre-commit sync dependencies
    - Execute `align-project-documents` after spec conversion and code/doc scans are complete.
    - Execute `maintain-project-constraints` immediately before the commit.
-6. Keep docs synchronized when needed
+7. Keep docs synchronized when needed
    - Apply the output from `archive-specs` when repository specs were converted or existing project docs were normalized into categorized project docs.
    - Apply the output from `align-project-documents` when behavior or usage changed.
    - Apply the output from `maintain-project-constraints` when agent workflow/rules changed.
-7. Commit
+8. Commit
    - Preserve user staging intent where possible.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
-8. Push
-   - Push commit(s) to the current branch.
+9. Push
+   - Push commit(s) to the intended branch.
+   - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
 
 ## Notes
 

package/develop-new-features/SKILL.md

@@ -28,13 +28,13 @@ description: >-
 ## Standards
 
 - Evidence: Review authoritative docs and the existing codebase before planning or implementation.
-- Execution: Run `generate-spec` for every new feature or product-behavior change, obtain approval, then continue through implementation, testing, and backfill until the approved plan is fully reconciled.
+- Execution: Use specs only for feature work that is genuinely multi-step, cross-surface, or higher risk; skip specs for obviously small/localized work and route that work to direct implementation or the appropriate maintenance skill instead.
 - Quality: Add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
 - Output: Keep the approved planning artifacts and the final implementation aligned with actual completion results.
 
 ## Goal
 
-Use a shared spec-generation workflow for all new feature work, then implement the approved behavior with strong test coverage and minimal rework.
+Use a shared spec-generation workflow for non-trivial new feature work, then implement the approved behavior with strong test coverage and minimal rework.
 
 ## Workflow
 
@@ -47,7 +47,15 @@ Use a shared spec-generation workflow for all new feature work, then implement t
 
 ### 2) Run `$generate-spec`
 
-- Specs are mandatory for every new feature, product behavior change, and greenfield project.
+- First decide whether the request truly belongs in this skill.
+- Do not use this skill or generate specs when the request is actually one of these:
+  - bug fixes or regressions that restore intended behavior without introducing new product behavior
+  - copy-only, styling-only, spacing-only, layout-only, or other purely presentational UI tweaks with localized impact
+  - simple configuration, constant, feature-flag, dependency, or content updates confined to one small area
+  - small refactors, naming cleanups, or internal code-health work with no externally visible behavior change
+  - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
+- In those cases, do not create `spec.md` / `tasks.md` / `checklist.md`; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
+- Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
 - Follow `$generate-spec` completely for:
   - generating `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`
   - filling BDD requirements and risk-driven test plans
@@ -98,7 +106,11 @@ Rules:
 
 - Backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow after implementation and testing.
 - In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- Mark every completed task in `tasks.md`, resolve every applicable checklist item, and explicitly label any remaining item as deferred or blocked with the reason.
+- Mark every completed task in `tasks.md`.
+- In `checklist.md`, update only the items that are actually applicable to the approved scope and executed validation.
+- Do not mark template alternatives, unused example rows, or non-applicable decision branches as completed just to make the file look fully checked.
+- Rewrite, remove, or leave `N/A` on template-only sections so the final checklist reflects the real work rather than the starter template.
+- Explicitly label any truly remaining applicable item as deferred or blocked with the reason.
 - Report the implemented scope, test execution, and any concrete `N/A` reasons.
 
 ## Working Rules
@@ -107,6 +119,7 @@ Rules:
 - Keep implementation traceable to approved requirement IDs and planned risks.
 - Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
+- Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.
 - If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
 
 ## References

package/develop-new-features/references/testing-e2e.md

@@ -32,4 +32,5 @@
 ## Spec/checklist authoring hints
 - Mark high-risk key paths in `spec.md` requirement descriptions.
 - Record E2E decisions, mapped test cases, and results in `checklist.md`.
+- When different flows need different strategies, create multiple decision records instead of forcing one shared E2E decision for the whole feature.
 - If skipping E2E, specify replacement integration test cases (`IT-xx`) and rationale in `checklist.md`.

package/enhance-existing-features/SKILL.md

@@ -48,9 +48,20 @@ Safely extend brownfield systems by exploring the existing codebase first, using
 Use the user's requested change together with the codebase exploration results to decide whether to generate specs.
 
 Trigger specs when any of the following is true:
-- high complexity changes
-- critical module changes
-- cross-module changes
+- the change introduces new user-visible behavior, not just a bug fix restoring intended behavior
+- requirements are ambiguous enough that approval on written scope, tradeoffs, or edge cases is useful
+- multiple modules, layers, services, or teams must stay aligned
+- the change touches critical flows, sensitive data, permissions, money movement, migrations, or irreversible operations
+- the risk profile is high enough that explicit requirement-to-test traceability will materially reduce mistakes
+
+Do not generate specs when the work is clearly small and localized, such as:
+- bug fixes or regressions that restore already-intended behavior without changing product scope
+- pure frontend polish: copy tweaks, styling, spacing, alignment, responsive touch-ups, visual cleanup, or simple template/view wiring
+- small configuration, constant, dependency, content, or feature-flag updates confined to one area
+- straightforward CRUD field additions, validation message tweaks, or one-path handler adjustments with limited blast radius
+- refactors, renames, dead-code cleanup, or observability-only changes that do not alter user-visible behavior
+
+When in doubt, prefer direct implementation for genuinely low-risk localized changes, and reserve specs for changes whose scope or risk would benefit from explicit approval artifacts.
 
 If triggered:
 - Run `$generate-spec` and follow its workflow completely.
@@ -108,7 +119,11 @@ Rules:
 
 - If specs were used, backfill `spec.md`, `tasks.md`, and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
 - In `spec.md`, mark each relevant requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- If specs were used, mark every completed task in `tasks.md`, resolve every applicable checklist item, and explicitly label any remaining item as deferred or blocked with the reason.
+- If specs were used, mark every completed task in `tasks.md`.
+- If specs were used, update only the applicable checklist items that correspond to real scope, chosen test strategy, and actual execution.
+- Do not mark unused template examples, mutually exclusive alternatives, or non-applicable branches as completed.
+- Remove, rewrite, or leave `N/A` on starter-template items when they do not belong to the real change.
+- Explicitly label any still-applicable remaining item as deferred or blocked with the reason.
 - If specs were not used, provide a concise execution summary including test IDs/results, regression coverage, mock scenario coverage, adversarial coverage, and any `N/A` reasons.
 
 ## Working Rules
@@ -117,6 +132,7 @@ Rules:
 - Always decide the need for specs only after exploring the existing codebase.
 - Maintain traceability between requirements, tasks, and tests when specs are present.
 - Treat checklists as living artifacts: adjust items to match real change scope.
+- Treat mutually exclusive template choices as a decision to record, not multiple boxes to finish.
 - Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
 - If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
 

package/enhance-existing-features/references/e2e-tests.md

@@ -22,4 +22,5 @@
 
 ## Recording rules
 - Specs flow: record E2E or replacement strategy with outcomes in `checklist.md`.
+- When different flows need different strategies, create multiple decision records in `checklist.md` so each flow/risk slice keeps its own rationale and linked case IDs.
 - Non-specs flow: explain E2E execution or replacement testing with rationale in the response.

package/generate-spec/SKILL.md

@@ -14,9 +14,9 @@ description: Generate and maintain shared feature planning artifacts (`spec.md`,
 
 ## Standards
 
-- Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans.
+- Evidence: Review the relevant code, configs, and authoritative docs before filling requirements or test plans; when external dependencies, libraries, frameworks, APIs, or platforms are involved, checking their official documentation is mandatory during spec creation.
 - Execution: Generate the planning files first, complete them with traceable requirements and risks, handle clarification updates, then wait for explicit approval before implementation.
-- Quality: Keep `spec.md`, `tasks.md`, and `checklist.md` synchronized and map each planned test to a concrete risk or requirement.
+- Quality: Keep `spec.md`, `tasks.md`, and `checklist.md` synchronized, map each planned test to a concrete risk or requirement, and tailor the templates so only applicable items remain active.
 - Output: Store planning artifacts under `docs/plans/{YYYY-MM-DD}_{change_name}/` and keep them concise, executable, and easy to update.
 
 ## Goal
@@ -29,6 +29,9 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Confirm the target workspace root, feature name, and a kebab-case `change_name`.
 - Review only the code, configuration, and external docs needed to understand the requested behavior.
+- If the change depends on frameworks, libraries, SDKs, APIs, CLIs, hosted services, or other external systems, find and read the relevant official documentation before drafting requirements.
+- Treat official documentation lookup as mandatory evidence gathering, not an optional refinement step.
+- Use the official docs to verify expected behavior, supported constraints, configuration surface, integration contracts, and any implementation limits that should shape the spec.
 - Record the references that should appear in `spec.md`.
 - Inspect existing `docs/plans/` directories before deciding whether to edit an existing plan set.
 - Reuse an existing plan set only when it clearly matches the same requested issue/change scope.
@@ -50,9 +53,11 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 ### 3) Fill `spec.md`
 
 - Keep the goal and scope concrete.
+- Ensure the described scope and requirements do not contradict the relevant official documentation or integration contracts.
 - Write functional behaviors in BDD form with `GIVEN`, `WHEN`, `THEN`, `AND`, and `Requirements`.
 - Make each requirement testable.
 - Cover boundaries, authorization, external dependency states, abuse/adversarial paths, failure handling, and any relevant idempotency/concurrency/data-integrity risks.
+- Record the official-doc references actually used for the spec, especially for external dependency behavior and constraints.
 - If requirements are unclear, list 3-5 clarification questions; otherwise write `None`.
 
 ### 4) Fill `tasks.md`
@@ -64,11 +69,15 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ### 5) Fill `checklist.md`
 
-- Use checkbox format `- [ ]` only.
+- Use checkbox format `- [ ]` for checklist items, except structured placeholder fields that are intentionally left for later fill-in.
 - Treat the template as a starting point and adapt it to the actual scope.
+- Remove or rewrite template examples that are not part of the real plan instead of leaving them as fake work to be checked later.
 - Map observable behaviors to requirement IDs and real test case IDs.
 - Record risk class, oracle/assertion focus, dependency strategy, and test results.
 - Property-based coverage is required for business-logic changes unless a concrete `N/A` reason is recorded.
+- For decision sections, create as many records as needed for distinct flows or risk slices; do not collapse unrelated decisions into one record.
+- Within each decision record, keep only the selected strategy or clearly mark the non-selected path as `N/A`; never treat mutually exclusive choices inside one record as multiple completed outcomes.
+- For completion-summary sections, create as many completion records as needed for distinct flows, requirement groups, or workstreams; do not force the whole spec into a single completion line when different parts finish differently.
 
 ### 6) Process clarifications and approval
 
@@ -82,6 +91,10 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 - Mark completed tasks in `tasks.md`.
 - Update `checklist.md` with real test outcomes, `N/A` reasons, and any scope adjustments.
+- Only mark checklist items complete when the work actually happened or the recorded decision actually applies.
+- Do not check off unused examples, placeholder rows, or non-selected decision options.
+- If different flows use different test strategies, preserve separate decision records in the final checklist instead of merging them into a misleading single summary.
+- If different parts of the approved scope have different completion states, preserve separate completion records in the final checklist instead of flattening them into one ambiguous status.
 - Remove stale placeholders or template-only guidance once the documents are finalized.
 
 ## Working Rules
@@ -89,6 +102,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - By default, write planning docs in the user's language.
 - Keep requirement IDs, task IDs, and test IDs traceable across all three files.
 - Prefer realistic coverage over boilerplate: add or remove checklist items based on actual risk.
+- Finalized planning docs should read like the actual approved plan and execution record, not like a fully checked starter template.
+- If official documentation materially constrains implementation choices, reflect that constraint explicitly in the spec instead of leaving it implicit.
 - Use kebab-case for `change_name`; avoid spaces and special characters.
 - Path rule: `scripts/...` and `references/...` in this file always mean paths under the current skill folder, not the target project root.
 - Never overwrite a nearby issue's plan set just because the technical area overlaps; shared modules are not sufficient evidence that the scope is the same.

package/generate-spec/references/templates/checklist.md

@@ -6,7 +6,11 @@
 ## Usage Notes
 - This checklist is a starter template. Add, remove, or rewrite items based on actual scope.
 - Use `- [ ]` for all items; mark completed items as `- [x]`.
+- The final completion summary section may use structured placeholders instead of checkboxes.
 - If an item is not applicable, keep `N/A` with a concrete reason.
+- Do not mark placeholder examples or mutually exclusive alternatives as completed unless they were actually selected and executed.
+- Duplicate or remove decision-record blocks as needed; the final document should contain as many records as the real change requires.
+- Duplicate or remove completion-record blocks as needed; the final document should contain as many records as the real change requires.
 - Suggested test result values: `PASS / FAIL / BLOCKED / NOT RUN / N/A`.
 - For business-logic changes, property-based coverage is required unless a concrete `N/A` reason is recorded.
 - Each checklist item should map to a distinct risk; avoid repeating shallow happy-path cases.
@@ -60,10 +64,19 @@
 - [ ] Assertions verify business outcomes and side effects/no-side-effects, not only "returns 200" or "does not throw".
 - [ ] Test fixtures are reproducible (fixed seed/clock/fixtures) or `N/A` is recorded with a concrete reason.
 
-## E2E Decision Record (pick one or customize)
-- [ ] Build E2E (case: [E2E-xx]; reason: [importance/complexity/cross-layer risk]).
-- [ ] Do not build E2E; cover with integration tests instead (alternative case: [IT-xx]; reason: [stability/cost/environment limitation]).
-- [ ] No additional E2E/integration hardening required (reason: [existing coverage already addresses risk]).
+## E2E / Integration Decision Records
+
+### Decision Record 1: [Flow / Requirement / Risk Slice]
+- Requirement mapping: [R?.? / CL-xx]
+- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
+- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
+- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
+
+### Decision Record 2: [Flow / Requirement / Risk Slice]
+- Requirement mapping: [R?.? / CL-xx]
+- Decision: [Build E2E / Cover with integration instead / Existing coverage already sufficient / N/A]
+- Linked case IDs: [E2E-xx / IT-xx / existing suite reference]
+- Reason: [importance, cross-layer risk, stability/cost tradeoff, or why no extra coverage is needed]
 
 ## Execution Summary (fill with actual results)
 - [ ] Unit tests: `PASS / FAIL / NOT RUN / N/A`
@@ -74,5 +87,16 @@
 - [ ] External service mock scenarios: `PASS / FAIL / NOT RUN / N/A`
 - [ ] Adversarial/penetration-style cases: `PASS / FAIL / NOT RUN / N/A`
 
-## Completion Rule
-- [ ] Agent has updated checkboxes, test outcomes, and necessary notes based on real execution (including added/removed items).
+## Completion Records
+
+### Completion Record 1: [Flow / Requirement Group / Workstream]
+- Requirement mapping: [R?.? / Task N / CL-xx]
+- Completion status: [completed / partially completed / blocked / deferred]
+- Remaining applicable items: [None / list remaining items]
+- Notes: [brief execution-backed summary]
+
+### Completion Record 2: [Flow / Requirement Group / Workstream]
+- Requirement mapping: [R?.? / Task N / CL-xx]
+- Completion status: [completed / partially completed / blocked / deferred]
+- Remaining applicable items: [None / list remaining items]
+- Notes: [brief execution-backed summary]

package/generate-spec/references/templates/spec.md

@@ -8,8 +8,12 @@
 [Describe the business goal and user value in one sentence.]
 
 ## Scope
-- In scope: [What is included in this change]
-- Out of scope: [What is explicitly excluded]
+
+### In Scope
+[What is included in this change]
+
+### Out of Scope
+[What is explicitly excluded]
 
 ## Functional Behaviors (BDD)
 
@@ -51,5 +55,6 @@
 ## References
 - Official docs:
   - [Link or document 1]
+  - [Link or document 2]
 - Related code files:
   - [File path 1]

package/maintain-skill-catalog/SKILL.md

@@ -16,7 +16,7 @@ description: Audit and maintain a repository of installable skills so the catalo
 
 - Evidence: Read the actual skill folders, validation scripts, repository docs, and local installed skill names before changing dependency classifications or catalog docs.
 - Execution: Audit first, classify findings, make focused catalog updates, then run the repo validators before finishing.
-- Quality: Avoid duplicate skills, avoid rewording behavior without checking the implementation, and distinguish aliases or local unpublished skills from true external dependencies.
+- Quality: Avoid duplicate skills, avoid rewording behavior without checking the implementation, distinguish aliases or local unpublished skills from true external dependencies, and enforce the repository's current metadata constraints such as `SKILL.md` frontmatter validity, description-length limits, and synchronized agent configs.
 - Output: Leave the catalog with synchronized skill metadata, dependency documentation, and validation status.
 
 ## Goal
@@ -35,6 +35,7 @@ Keep a skill repository coherent when many top-level skills evolve together.
 ### 2) Audit dependency declarations and shared conventions
 
 - Use the standardized `## Dependencies` section as the source of truth for skill-to-skill relationships.
+- Read the current validator scripts before changing frontmatter-heavy files so metadata limits come from implementation rather than memory.
 - Classify each dependency as:
   - vendored in this repository
   - local/private skill that should not be documented as external
@@ -49,6 +50,7 @@ Keep a skill repository coherent when many top-level skills evolve together.
 - Update `README.md` skill lists and external dependency sections when the catalog actually changes.
 - Update `AGENTS.md` when the repository gains or loses a user-visible capability or a standing convention changes.
 - When creating a new shared skill, align naming, frontmatter, `agents/openai.yaml`, and any lightweight README with neighboring skills.
+- When a failure comes from validator drift or a metadata constraint that was not caught early, tighten the validator or CI path in the same change instead of only fixing the offending skill text.
 - Do not treat unpublished local skills as external dependencies just because they are not yet installed elsewhere.
 
 ### 4) Validate the catalog after changes

package/open-github-issue/README.md

@@ -1,15 +1,15 @@
 # Open GitHub Issue
 
-Structured GitHub issue and feature-proposal publishing with deterministic authentication fallback and repository-language-aware issue bodies.
+Structured GitHub issue publishing across multiple issue categories with deterministic authentication fallback and repository-language-aware issue bodies.
 
-This skill helps agents publish confirmed findings or accepted feature proposals as GitHub issues without embedding repository resolution, auth handling, and language detection logic into every other workflow.
+This skill helps agents publish confirmed findings, accepted proposals, documentation gaps, security risks, observability gaps, and performance issues as GitHub issues without embedding repository resolution, auth handling, and language detection logic into every other workflow.
 
 ## What this skill provides
 
 - Target repository resolution from `--repo` or current git `origin`.
 - Strict auth fallback order: `gh` login -> `GITHUB_TOKEN`/`GH_TOKEN` -> draft only.
 - Issue body language detection based on the target repository README.
-- Consistent structured issue bodies for both problem issues and feature proposal issues.
+- Consistent structured issue bodies for `problem`, `feature`, `performance`, `security`, `docs`, and `observability` issues.
 - Machine-readable JSON output so parent skills can report publication status consistently.
 
 ## Repository structure
@@ -33,7 +33,7 @@ cp -R open-github-issue "$CODEX_HOME/skills/open-github-issue"
 Invoke the skill in your prompt:
 
 ```text
-Use $open-github-issue to publish this confirmed finding or accepted feature proposal to GitHub.
+Use $open-github-issue to publish this confirmed finding or accepted proposal to GitHub.
 ```
 
 The bundled script can also be called directly:
@@ -58,6 +58,19 @@ python scripts/open_github_issue.py \
   --repo owner/repo
 ```
 
+```bash
+python scripts/open_github_issue.py \
+  --issue-type security \
+  --title "[Security] Missing authorization check on admin export" \
+  --problem-description "The admin export endpoint can be reached without verifying the caller's admin role." \
+  --severity high \
+  --affected-scope "/admin/export endpoint and exported customer data" \
+  --impact "Unauthorized users may access privileged exports containing sensitive business data." \
+  --evidence "Code path review and reproduced requests show the handler validates session presence but not the admin permission gate." \
+  --suggested-action "Add explicit authorization enforcement, regression tests, and audit logging for denied access attempts." \
+  --repo owner/repo
+```
+
 ## Publication behavior
 
 For each issue:
@@ -66,7 +79,7 @@ For each issue:
 2. Otherwise, if `GITHUB_TOKEN` or `GH_TOKEN` exists, publish via GitHub REST API.
 3. Otherwise, return draft issue content without blocking the caller.
 
-Problem issues always include exactly three sections:
+`problem` issues always include exactly three sections:
 
 - `Problem Description`
 - `Suspected Cause`
@@ -80,7 +93,7 @@ Within `Problem Description`, include:
 
 For Chinese-language repositories, use translated section titles with the same meaning.
 
-Feature proposal issues always include:
+`feature` issues always include:
 
 - `Feature Proposal`
 - `Why This Is Needed`
@@ -88,6 +101,35 @@ Feature proposal issues always include:
 
 For Chinese-language repositories, use translated section titles with the same meaning.
 
+`performance` issues include:
+
+- `Performance Problem`
+- `Impact`
+- `Evidence`
+- `Suggested Action`
+
+`security` issues include:
+
+- `Security Risk`
+- `Severity`
+- `Affected Scope`
+- `Impact`
+- `Evidence`
+- `Suggested Mitigation`
+
+`docs` issues include:
+
+- `Documentation Gap`
+- `Evidence`
+- `Suggested Update`
+
+`observability` issues include:
+
+- `Observability Gap`
+- `Impact`
+- `Evidence`
+- `Suggested Instrumentation`
+
 ## Output
 
 The script prints JSON including:

package/open-github-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: open-github-issue
-description: Publish structured GitHub issues and feature proposals with deterministic auth fallback, target-repo resolution, README-based language detection, and draft-only fallback when authentication is unavailable. Use when users ask to open GitHub issues from confirmed findings, accepted feature proposals, or prepared issue content.
+description: Publish structured GitHub issues across multiple issue categories with deterministic auth fallback, target-repo resolution, README-based language detection, and draft-only fallback when authentication is unavailable. Use when users ask to open GitHub issues from confirmed findings, accepted proposals, documentation gaps, security risks, observability gaps, or prepared issue content.
 ---
 
 # Open GitHub Issue
@@ -14,14 +14,14 @@ description: Publish structured GitHub issues and feature proposals with determi
 
 ## Standards
 
-- Evidence: Require structured issue inputs, detect repository language from the target README instead of guessing, and for `problem` issues capture BDD-style expected vs current behavior with an explicit delta.
+- Evidence: Require structured issue inputs, detect repository language from the target README instead of guessing, and enforce category-specific required fields so each issue type matches the situation being reported.
 - Execution: Resolve the repo, normalize the issue body, publish with strict auth order, then return the publication result.
 - Quality: Preserve upstream evidence, localize only the structural parts, keep publication deterministic and reproducible, and make behavioral mismatches easy for maintainers to verify.
 - Output: Return publication mode, issue URL when created, rendered body, and any publish error in the standardized JSON contract.
 
 ## Overview
 
-Use this skill to publish a structured GitHub issue or feature proposal deterministically.
+Use this skill to publish structured GitHub issues deterministically across several common issue situations.
 
 It is designed to be reusable by other skills that already know the issue title and evidence, but need a consistent way to:
 
@@ -36,7 +36,7 @@ It is designed to be reusable by other skills that already know the issue title
 - Prefer authenticated `gh` CLI first, then GitHub token, then draft-only fallback.
 - Detect repository issue language from the target remote README instead of guessing.
 - Preserve upstream evidence content; only localize section headers and default fallback text.
-- Make the issue type explicit: `problem` for defects/incidents, `feature` for proposals.
+- Make the issue type explicit: `problem`, `feature`, `performance`, `security`, `docs`, or `observability`.
 - For `problem` issues, describe the expected behavior and current behavior with BDD-style `Given / When / Then`, then state the behavioral difference explicitly.
 
 ## Workflow
@@ -59,6 +59,27 @@ It is designed to be reusable by other skills that already know the issue title
      - `proposal` (optional; defaults to title when omitted)
      - `reason`
      - `suggested-architecture`
+   - For `performance` issues, require:
+     - `problem-description`
+     - `impact`
+     - `evidence`
+     - `suggested-action`
+   - For `security` issues, require:
+     - `problem-description`
+     - `severity`
+     - `affected-scope`
+     - `impact`
+     - `evidence`
+     - `suggested-action`
+   - For `docs` issues, require:
+     - `problem-description`
+     - `evidence`
+     - `suggested-action`
+   - For `observability` issues, require:
+     - `problem-description`
+     - `impact`
+     - `evidence`
+     - `suggested-action`
    - If reproduction is missing for a `problem` issue, insert the default non-reproducible note in the target issue language.
 3. Detect issue language
    - Read the target repository README from GitHub.
@@ -98,6 +119,59 @@ python scripts/open_github_issue.py \
   --repo <owner/repo>
 ```
 
+Performance issue:
+
+```bash
+python scripts/open_github_issue.py \
+  --issue-type performance \
+  --title "[Performance] Slow dashboard query under large tenants" \
+  --problem-description "Dashboard loading time degrades sharply once tenant data exceeds current pagination assumptions." \
+  --impact "Users wait 8-12 seconds before the page becomes interactive; this blocks support workflows." \
+  --evidence "Profiler output, slow-query logs, and production timings all point to repeated full-table scans in the summary query path." \
+  --suggested-action "Add bounded pagination, pre-aggregated summaries, and an index review for the offending query path." \
+  --repo <owner/repo>
+```
+
+Security issue:
+
+```bash
+python scripts/open_github_issue.py \
+  --issue-type security \
+  --title "[Security] Missing authorization check on admin export" \
+  --problem-description "The admin export endpoint can be reached without verifying the caller's admin role." \
+  --severity high \
+  --affected-scope "/admin/export endpoint and exported customer data" \
+  --impact "Unauthorized users may access privileged exports containing sensitive business data." \
+  --evidence "Code path review and reproduced requests show the handler validates session presence but not the admin permission gate." \
+  --suggested-action "Add explicit authorization enforcement, regression tests, and audit logging for denied access attempts." \
+  --repo <owner/repo>
+```
+
+Docs issue:
+
+```bash
+python scripts/open_github_issue.py \
+  --issue-type docs \
+  --title "[Docs] Deployment guide omits required Redis configuration" \
+  --problem-description "The deployment guide does not mention the required Redis URL and worker startup order." \
+  --evidence "README deploy steps differ from the actual compose file and runtime startup checks." \
+  --suggested-action "Update deployment docs with required env vars, startup order, and a minimal validation checklist." \
+  --repo <owner/repo>
+```
+
+Observability issue:
+
+```bash
+python scripts/open_github_issue.py \
+  --issue-type observability \
+  --title "[Observability] Missing request identifiers in payment retry logs" \
+  --problem-description "Retry logs do not include stable request or trace identifiers, so multi-line failures cannot be correlated quickly." \
+  --impact "On-call engineers cannot isolate a single failing payment flow without manual log stitching." \
+  --evidence "Current retry log lines include endpoint and error text only; incident review required manual timestamp matching." \
+  --suggested-action "Add request_id, trace_id, upstream target, and retry attempt fields to retry logs and dashboard facets." \
+  --repo <owner/repo>
+```
+
 ## Output contract
 
 The script prints JSON with these fields:
@@ -115,11 +189,12 @@ The script prints JSON with these fields:
 
 When another skill depends on `open-github-issue`:
 
-- Pass exactly one confirmed problem or one accepted feature proposal per invocation.
+- Pass exactly one confirmed issue or one accepted proposal per invocation.
 - Prepare evidence or proposal details before calling this skill; do not ask this skill to infer root cause or architecture.
 - For `problem` issues, pass a `problem-description` that contains `Expected Behavior (BDD)`, `Current Behavior (BDD)`, and `Behavior Gap`; the difference must be explicit, not implied.
 - Reuse the returned `mode`, `issue_url`, and `publish_error` in the parent skill response.
 - For accepted feature proposals, pass `--issue-type feature` plus `--proposal`, `--reason`, and `--suggested-architecture`.
+- For security, performance, docs, or observability findings, choose the matching `issue-type` instead of overloading `problem`.
 
 ## Resources
 

package/open-github-issue/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Open GitHub Issue"
-  short_description: "Publish structured issues and feature proposals"
-  default_prompt: "Use $open-github-issue to publish a structured GitHub issue or feature proposal from prepared content, resolve the target repo, detect README language for issue sections, and fall back deterministically from gh CLI to GitHub token to draft-only output."
+  short_description: "Publish structured issues across multiple categories"
+  default_prompt: "Use $open-github-issue to publish a structured GitHub issue from prepared content, choose the correct issue category such as problem, feature, performance, security, docs, or observability, resolve the target repo, detect README language for issue sections, and fall back deterministically from gh CLI to GitHub token to draft-only output."