@laitszkin/apollo-toolkit 2.0.0

package/develop-new-features/README.md

@@ -0,0 +1,52 @@
+# develop-new-features
+
+A spec-first feature development skill for new behavior and greenfield work. It delegates shared planning-doc generation to `generate-spec`, then implements the approved feature with risk-driven testing.
+
+## Key capabilities
+
+- Requires `generate-spec` before any implementation starts.
+- Treats `spec.md`, `tasks.md`, and `checklist.md` as approval-gated artifacts, not optional notes.
+- Covers unit, regression, property-based, integration, E2E, and adversarial testing based on actual risk.
+- Reuses existing architecture and avoids speculative expansion.
+- Backfills planning docs after implementation and testing complete.
+
+## Repository layout
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+└── references/
+    ├── testing-unit.md
+    ├── testing-property-based.md
+    ├── testing-integration.md
+    └── testing-e2e.md
+```
+
+## Workflow summary
+
+1. Review only the official docs and code paths needed for the feature.
+2. Run `generate-spec` to create and maintain `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+3. Wait for explicit approval on the spec set.
+4. Implement the approved behavior with minimal changes.
+5. Run risk-driven tests and backfill `tasks.md` and `checklist.md`.
+
+## Testing expectations
+
+- Unit: changed logic, boundaries, failure paths.
+- Regression: pin down bug-prone or high-risk behavior.
+- Property-based: required for business logic unless concrete `N/A` is recorded.
+- Integration: cover the user-critical logic chain.
+- E2E: cover the most important success and denial/failure paths when justified.
+- Adversarial: include abuse, malformed input, privilege, replay, concurrency, and edge-combination cases when relevant.
+
+## References
+
+- Shared planning workflow: `generate-spec`
+- Unit testing guide: `references/testing-unit.md`
+- Property-based testing guide: `references/testing-property-based.md`
+- Integration testing guide: `references/testing-integration.md`
+- E2E testing guide: `references/testing-e2e.md`

package/develop-new-features/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: develop-new-features
+description: >-
+  Spec-first feature development workflow for new behavior and greenfield
+  features. Depends on `generate-spec` for shared planning artifacts before
+  coding, then implements the approved feature with risk-driven test coverage.
+  Use when users ask to design or implement new features, change product
+  behavior, request a planning-first process, or ask for a greenfield feature.
+  Tests must not stop at happy-path validation: for business-logic changes
+  require property-based testing unless explicitly `N/A` with reason, design
+  adversarial/regression/authorization/idempotency/concurrency coverage where
+  relevant, use mocks for external services in logic chains, and verify
+  meaningful business outcomes rather than smoke-only success.
+---
+
+# Develop New Features
+
+## Dependencies
+
+- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, clarification handling, approval gating, and status backfill.
+- Conditional: none.
+- Optional: none.
+- Fallback: If `generate-spec` is unavailable, stop and report the missing dependency.
+
+## 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 implement minimally.
+- 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.
+
+## Workflow
+
+### 1) Review authoritative docs first
+
+- Identify the stack, libraries, APIs, and external dependencies involved.
+- Use official documentation as the source of truth.
+- Prefer Context7 for framework/library APIs; use web for the latest official docs when needed.
+- Record only the references required for this feature.
+
+### 2) Run `$generate-spec`
+
+- Specs are mandatory for every new feature, product behavior change, and greenfield project.
+- 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
+  - handling clarification responses
+  - obtaining explicit approval before coding
+  - backfilling document status after implementation and testing
+- Do not modify product code before the approved spec set exists.
+
+### 3) Explore architecture and reuse opportunities
+
+- Trace entrypoints, module boundaries, data flow, and integration points relevant to the new behavior.
+- Identify reusable components, patterns, and configuration paths before adding new code.
+- Keep a concise map of likely files to modify so implementation stays scoped.
+
+### 4) Implement after approval
+
+- Reuse existing patterns and abstractions when possible.
+- Keep changes focused and avoid speculative scope expansion.
+- Update environment examples only when new inputs are actually required.
+
+### 5) Testing coverage (required)
+
+For every non-trivial change, evaluate all categories and add test cases or record justified `N/A`:
+- Start from a risk inventory, not from the happy path: assess misuse/abuse, authorization, invalid transitions, idempotency, replay/duplication, concurrency/races, data-integrity, and partial-failure/rollback risks.
+- Unit tests: changed logic, boundaries, failure paths, and exact error/side-effect expectations.
+- Regression tests: bug-prone or high-risk behavior that should never silently regress again.
+- Property-based tests: required for business-logic changes unless truly unsuitable; use them for invariants, generated business input spaces, state-machine/metamorphic checks when useful, and output expectation checks.
+- Integration tests: user-critical logic chain across modules/layers.
+- E2E tests: key user-visible path impacted by this change; prefer one minimal critical success path plus one highest-value denial/failure path when the risk warrants it.
+- Adversarial/penetration-style cases: abuse paths, malformed inputs, forged identities/privileges, invalid transitions, replay/duplication, stale/out-of-order events, toxic payload sizes, and risky edge combinations.
+
+Rules:
+- If E2E is too costly or unstable, add stronger integration coverage for the same risk and record the reason in the checklist.
+- If property-based testing is not suitable, record `N/A` with a concrete reason.
+- For logic chains with external services, mock or fake those services unless the real contract itself is under test; simulate diverse external states and verify the business chain remains correct.
+- Where the feature can partially commit work, test rollback, compensation, or no-partial-write behavior explicitly.
+- Each test must assert a meaningful oracle: exact business output, persisted state, emitted side effects, or intentional lack of side effects. Avoid assertion-light smoke tests and snapshot-only coverage.
+- Run relevant tests when possible and fix failures.
+
+### 6) Completion updates
+
+- Backfill `tasks.md` and `checklist.md` through `$generate-spec` workflow after implementation and testing.
+- Report the implemented scope, test execution, and any concrete `N/A` reasons.
+
+## Working Rules
+
+- By default, write planning docs in the user's language.
+- 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".
+
+## References
+
+- `$generate-spec`: shared planning and approval workflow.
+- `references/testing-unit.md`: unit testing principles.
+- `references/testing-property-based.md`: property-based testing principles.
+- `references/testing-integration.md`: integration testing principles.
+- `references/testing-e2e.md`: E2E decision and design principles.

package/develop-new-features/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Develop New Features"
+  short_description: "Spec-first feature development that depends on generate-spec"
+  default_prompt: "Use $develop-new-features to design new behavior through a spec-first workflow: review the required external docs, run $generate-spec to create and maintain docs/plans/<date>_<change_name>/{spec.md,tasks.md,checklist.md}, wait for explicit approval, then implement the approved feature with risk-driven tests and backfill the planning docs after execution."

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

@@ -0,0 +1,35 @@
+# E2E Testing Principles
+
+## Core rules
+- E2E is not decided solely by explicit user request.
+- The agent must decide E2E based on feature importance, complexity, and cross-layer risk.
+- For high-risk key user paths, create the smallest necessary E2E coverage first.
+- If E2E is unstable, too costly, or environment-limited, add integration coverage for equivalent risk and record the alternative.
+
+## Purpose
+- Verify critical end-to-end user paths are usable.
+- Catch behavior gaps after cross-system/cross-layer integration.
+- Provide confidence close to real usage for high-risk scenarios.
+
+## Decision criteria
+- Importance: core feature, critical revenue flow, or high-impact process.
+- Complexity: multi-step state transitions, branching flows, cross-service collaboration.
+- Risk: historical regressions, fragile integrations, major user-visible failures.
+- Maintainability: stable environment and controllable test data.
+
+## Not suitable when
+- Feature risk is low and unit/integration tests already cover it sufficiently.
+- E2E is unstable and disproportionately expensive while integration tests can cover key risk.
+
+## Design guidance
+- Cover only the most critical paths; avoid expanding into full UI test suites.
+- Keep test data controllable (fixed seeds or recyclable fixtures).
+- Prioritize stability; avoid brittle external dependencies, use controlled substitutes if needed.
+- Prefer one critical success path and one highest-value denial/failure path over many shallow happy-path journeys.
+- Assert business-visible outcomes, not just DOM presence: final state, permission denial, user-facing error, persisted result, or prevented duplicate action.
+- Keep cost decisions explicit: document why E2E is done or not done and what alternative strategy is used.
+
+## 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`.
+- If skipping E2E, specify replacement integration test cases (`IT-xx`) and rationale in `checklist.md`.

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

@@ -0,0 +1,42 @@
+# Integration Testing Principles
+
+## Purpose
+- Verify collaboration across modules/layers and external dependencies.
+- Cover integration risks unit tests cannot capture (sequence, config, IO failure).
+- Validate user-critical business logic chains under realistic component interaction and controlled external-service scenarios.
+
+## When to use
+- Interface interactions between modules (for example service ↔ repository).
+- Changes touching IO dependencies such as DB, RPC, files, cache, queues.
+- Behaviors that depend on configuration combinations or environment differences.
+- The correctness question is about the whole business logic chain rather than one isolated function.
+- As minimum safety replacement when E2E is not suitable.
+
+## Not suitable when
+- Single pure-function or pure-logic behavior (use unit tests).
+- Full end-to-end user flow can be stably covered by E2E.
+
+## Relationship with E2E
+- If change importance/complexity is high and E2E is feasible, prefer minimal E2E for key paths.
+- If E2E is hard or too costly, integration tests must cover equivalent key risks.
+- Record replacement mapping in `checklist.md` (E2E-xx ↔ IT-xx) with rationale.
+
+## Design guidance
+- Focus on high-value integration points; each test should justify risk/value.
+- Keep dependencies inside the application boundary near-real where practical.
+- Mock/fake external services at the business-chain boundary unless the real service contract itself is what needs verification.
+- Build scenario matrices for external states such as success, timeout, retries exhausted, partial data, stale data, duplicate callbacks, inconsistent responses, and permission failures.
+- Add adversarial/penetration-style cases for abuse paths such as invalid transitions, replay, double-submit, forged identifiers, or out-of-order events when those risks exist.
+- When workflows can partially commit, assert rollback/compensation/no-partial-write behavior instead of only final status codes.
+- Assert business outcomes across boundaries: persisted state, emitted events, deduplication, retry accounting, audit trail, or intentional absence of writes/notifications.
+- Add at least one regression-style integration test for the highest-risk chain whenever the change fixes a bug or touches a historically fragile path.
+- Keep reproducible: controlled test data and recoverable environment.
+- Keep cost controlled; avoid broad redundant coverage (leave that to unit tests).
+
+## Spec/checklist authoring hints
+- Dependency scope: list involved modules/external systems.
+- Scenario: describe cross-module flow or critical branch.
+- Risk: explain what integration failure, misconfiguration, or business-chain break this test can reveal.
+- External dependency strategy: specify which services are mocked/faked versus near-real and why.
+- Scenario matrix: list the external states or adversarial paths covered.
+- Map behavior, test IDs, and test outcomes in `checklist.md`.

package/develop-new-features/references/testing-property-based.md

@@ -0,0 +1,44 @@
+# Property-based Testing Principles
+
+## Purpose
+- Verify invariants/properties hold across broad input spaces.
+- Validate business rules by generating or exhaustively enumerating meaningful input spaces and checking outputs against expected business behavior.
+- Catch combinational, adversarial, and boundary behaviors that fixed examples often miss.
+
+## When to use
+- Algorithms, transformations, serialization/deserialization, sorting, aggregation.
+- Behaviors requiring consistency or reversibility (for example round-trip).
+- Data structures or state transitions with clear invariants.
+- Business logic where the rule can be stated as input/output expectations, allowed states, forbidden states, or safety constraints.
+- Logic chains that depend on external services, when those services can be replaced by controllable mocks/fakes and their states generated as part of the test space.
+
+## Not suitable when
+- The main thing being validated is the real integration contract with external systems or live IO (use integration tests).
+- UI/interactive flows without stable invariants.
+- Very small discrete input spaces (unit tests are sufficient).
+
+## Design guidance
+- Properties must be explicit and machine-verifiable, whether they are invariants, allowed outcome sets, rejection rules, or business-output predicates.
+- Generators should cover normal cases, boundaries, extremes, malformed inputs, and suspicious/adversarial combinations.
+- Prefer modeling business rules directly: generate inputs, run the logic, then assert the output/error/state transition matches the rule.
+- When the behavior is stateful, prefer state-machine or sequence-based properties over isolated single-call generators.
+- When exact outputs are hard to predict, use metamorphic properties (for example reordering, retrying, deduplicating, or replaying inputs should preserve an allowed relation).
+- For external-service-dependent logic, mock/fake the service and generate multiple service states (success, timeout, empty, partial, stale, inconsistent, duplicate, rejected).
+- Ensure reproducibility (fixed seed or replayable input generation) and preserve failing seeds/examples for regression coverage.
+- Complement unit tests; avoid duplicating fixed-case tests.
+- Control cost with reasonable sample counts and input-size limits.
+
+## Common property examples (description level)
+- `deserialize(serialize(x)) == x`
+- Sorted output is monotonic and preserves element multiset.
+- Merge/split operations preserve total element count.
+- Idempotency: repeating the same operation does not change results.
+- Invalid or unauthorized generated inputs always fail with an expected error/result class.
+- Generated order/payment/state-transition inputs always end in an allowed business state.
+- Under generated mocked service states, the business logic chain still satisfies fallback/retry/compensation rules.
+
+## Spec/checklist authoring hints
+- Property/rule: one sentence stating the rule that must always hold or the allowed outcomes that must contain the result.
+- Generator strategy: input range, distribution, emphasized boundaries, and any adversarial or external-state dimensions.
+- Oracle/check: describe how the test decides correctness (predicate, allow-list, reference model, or expected error class).
+- Purpose: explain correctness/risk reduction value of this property.

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

@@ -0,0 +1,37 @@
+# Unit Testing Principles
+
+## Purpose
+- Verify correctness of the smallest testable unit (function, method, or pure logic module).
+- Provide fast feedback with low-cost failure localization.
+
+## When to use
+- Core business logic and critical branches.
+- Boundary conditions (upper/lower limits, null/empty, extreme values).
+- Error handling and exception paths (invalid input, incompatible state, etc.).
+
+## Not suitable when
+- Behavior requires cross-module or external dependency verification (use integration tests).
+- Full user-flow validation is required (evaluate E2E first; if not suitable, use integration tests to cover risk).
+
+## Design guidance
+- Isolate external dependencies with mock/stub/fake; avoid DB/RPC/file IO.
+- Keep tests small and focused: one test, one behavior/failure mode.
+- Do not stop at happy-path assertions; verify exact errors, rejected states, and intentional lack of side effects when the unit should block an action.
+- Cover both success and failure branches.
+- Where the input space is small and discrete, exhaustively enumerate business inputs and expected outputs.
+- Prefer table-driven cases when many small business permutations share the same oracle.
+- Add regression tests for bug-prone or high-risk logic so previously broken behavior cannot silently return.
+- If the unit owns authorization, invalid transition, idempotency, or concurrency decisions, test those denials explicitly.
+- Keep tests reproducible: avoid nondeterministic time/random/global state.
+- Avoid assertion-light smoke tests and snapshot-only coverage unless the snapshot has a strict business oracle behind it.
+- Map tests to requirements: each core requirement should have at least one unit test.
+
+## Spec/checklist authoring hints
+- Scenario: describe input and initial state mapped to one requirement/boundary.
+- Expected result: verifiable output, state change, or error.
+- Purpose: explain which risk or bug type this test prevents.
+
+## Common examples (description level)
+- Return a specific error when input is out of allowed range.
+- Handle empty list/empty string input with expected behavior.
+- Ensure output matches definition after state/flag switching.

package/discover-edge-cases/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v0.2.1] - 2026-02-17
+
+### Changed
+- Remove `submit-changes` skill dependency from no-diff release flow while keeping the PR workflow.
+- Update skill and README guidance to use direct git commit/push before opening a PR.
+
+## [v0.2.0] - 2026-02-17
+
+### Added
+- Add no-diff workflow guidance to scan the whole codebase for actionable edge cases.
+- Add release-flow guidance for no-diff fixes: create worktree, use `submit-changes`, and open a PR.
+
+### Changed
+- Clarify scope selection logic: `git diff` path uses changed files only; no-diff path uses full-codebase scan.
+- Expand README examples to include a no-diff prompt and expected execution path.

package/discover-edge-cases/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/discover-edge-cases/README.md

@@ -0,0 +1,87 @@
+# discover-edge-cases
+
+`discover-edge-cases` is a Codex skill for discovering reproducible edge-case risks and coverage gaps.
+
+## Brief introduction
+
+This skill is discovery-oriented. It scans the current diff by default, or the full codebase
+when there is no diff, then validates the highest-risk edge cases with concrete evidence.
+It does not write tests, patch code, or open PRs.
+
+It follows a strict workflow:
+1. Detect whether `git diff` exists.
+2. Inspect only changed files plus minimal dependencies, or perform a full-project scan when no diff exists.
+3. Run `harden-app-security` as an adversarial dependency for code-affecting scope.
+4. Probe the highest-risk edge cases and gather concrete evidence.
+5. Reproduce confirmed issues at least twice and check nearby variants.
+6. Prioritize confirmed findings and report hardening guidance only.
+
+## When to use
+
+Use this skill when a task asks you to:
+- find edge-case risks in a diff or codebase,
+- validate unusual inputs and error paths,
+- assess hardening gaps around null/empty/boundary handling,
+- review retries, timeouts, degradation paths, or stateful failure modes.
+
+## Core principles
+
+- Scope is `git diff` plus the minimal dependency chain by default.
+- If `git diff` is empty, run a full-codebase scan focused on high-risk modules.
+- Treat prior authorship as irrelevant; even code written earlier in the same conversation must be challenged like third-party code.
+- Decisions must be evidence-based; speculative ideas stay marked as hypotheses.
+- Keep only reproducible findings with exact evidence.
+- Run `harden-app-security` as a required adversarial cross-check for code-affecting scope.
+- Report recommended fixes and test ideas, but do not implement them in this skill.
+
+## External API requirements
+
+When the selected scope involves external API calls, this skill requires checks for:
+- health/availability handling,
+- graceful handling of `429` and `500` responses,
+- actionable error logging (status code, request id, retry count, latency).
+
+## Example
+
+Prompt example:
+
+```text
+Please review this PR diff and find the 3 highest-risk edge cases.
+Validate null input, boundary timestamp, and API 429 retry behavior.
+Only report confirmed findings with reproduction evidence and suggested test coverage.
+```
+
+Expected behavior:
+- only changed files and minimal dependency chain are investigated,
+- each finding includes reproducible evidence,
+- speculative ideas are separated from confirmed issues,
+- the output stays discovery-only with no code edits.
+
+No-diff prompt example:
+
+```text
+There is no git diff in this repo. Scan the whole codebase for high-risk edge cases.
+If you find any actionable issues, reproduce them with evidence and report the highest-priority findings only.
+```
+
+## References
+
+- [`SKILL.md`](./SKILL.md) - full workflow and execution rules.
+- [`references/architecture-edge-cases.md`](./references/architecture-edge-cases.md) - cross-module/system-level edge-case checklist.
+- [`references/code-edge-cases.md`](./references/code-edge-cases.md) - code-level input, boundary, and error-path checklist.
+
+## Repository structure
+
+```text
+.
+├── LICENSE
+├── SKILL.md
+├── README.md
+└── references
+    ├── architecture-edge-cases.md
+    └── code-edge-cases.md
+```
+
+## License
+
+MIT

package/discover-edge-cases/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: discover-edge-cases
+description: Discover reproducible edge-case risks in changed code or a selected codebase scope, prove them with concrete evidence, and report prioritized findings without modifying implementation. Use when users ask to find edge cases, assess hardening gaps, or validate that unusual inputs and error paths are covered.
+---
+
+# Discover Edge Cases
+
+## Dependencies
+
+- Required: none.
+- Conditional: `harden-app-security` for code-affecting scopes before finalizing the report.
+- Optional: none.
+- Fallback: If the required security cross-check is unavailable for a code-affecting scope, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Keep only reproducible findings backed by code, tests, runtime output, or direct reproduction steps.
+- Execution: Determine scope first, run focused probes, confirm reproducibility, then report findings without remediation.
+- Quality: Separate confirmed findings from hypotheses and cover boundary, failure, stateful, and observability edge cases that matter to the scope.
+- Output: Return prioritized findings, edge-case evidence, risk assessment, hardening guidance, and residual risk only.
+
+## Overview
+
+Use this skill to discover edge-case failures and coverage gaps with evidence-first analysis. The goal is to surface reproducible findings, not to remediate them.
+
+## Non-negotiable Boundaries
+
+- This skill is discovery-only: do not edit code, do not add or modify tests, and do not open PRs.
+- Keep only reproducible findings with clear evidence.
+- Mark unverified ideas as hypotheses and separate them from confirmed findings.
+- If the task also requires remediation, finish this discovery pass first, then hand off confirmed findings to another implementation workflow.
+- Discard authorship bias completely: treat code written earlier in the conversation or by this agent as untrusted until evidence proves otherwise.
+
+## Workflow
+
+### 1) Determine scan scope (required)
+
+- Run `git diff --name-only` first.
+- If diff exists: inspect only changed files plus the minimum dependency chain required to validate suspected edge cases.
+- If no diff exists: scan the full project, prioritizing core domain logic, external API boundaries, stateful workflows, and concurrency-sensitive modules.
+- If no actionable issue is found, report `No actionable edge-case finding identified` and stop.
+
+### 2) Build a factual baseline
+
+- Read the relevant code paths end-to-end before judging behavior.
+- Re-derive behavior from code, tests, runtime output, and reproduced inputs only; ignore prior intent, authorship, or confidence from earlier turns.
+- Clarify input/output contracts: types, valid ranges, null handling, ordering assumptions, retry/error behavior, and state transitions.
+- Run existing tests or a minimal reproduction when needed to confirm actual vs expected behavior.
+- Record exact evidence with file references (`path:line`) and observable symptoms.
+
+### 3) Execute focused edge-case probes
+
+Prioritize 2-5 high-risk cases directly tied to the selected scope:
+
+- Empty collections / empty strings / None / null
+- Boundary values: 0, 1, -1, max/min limits, overflow
+- Duplicate, ordering, sorting, or deduplication assumptions
+- Exception paths: external dependency failure, timeout, retry, or partial data missing
+- Invalid formats: malformed strings, invalid date/timezone, or unexpected types
+- Concurrency/reentrancy: repeated calls, state contamination, or race windows
+- Architecture-level edge cases: backpressure, resource exhaustion, timeout propagation, or partial commit/rollback behavior
+
+For broader coverage, load references as needed:
+
+- `references/architecture-edge-cases.md`
+- `references/code-edge-cases.md`
+
+#### External API checks
+
+If the scope includes external API calls, validate:
+
+- observable health/availability handling,
+- degradation behavior for at least HTTP 429 and 500,
+- actionable error logging (status code, request id, retry count, latency) to avoid silent failures.
+
+### 4) Confirm reproducibility
+
+- Reproduce each confirmed issue at least twice through the same trigger path.
+- For high-risk findings, try nearby variants such as boundary neighbors, empty vs null, malformed vs well-typed invalid input, repeated calls, and stale ordering.
+- Capture the exact command, request, or input together with the observed failure or missing protection.
+- Keep unverified ideas as hypotheses only.
+
+### 5) Prioritize confirmed findings
+
+- Rank findings by user impact, exploitability or frequency, and blast radius.
+- Call out data-integrity, state corruption, silent failure, retry storm, and cross-module propagation risks explicitly.
+- Prefer fewer, stronger findings over many speculative ones.
+
+### 6) Report findings only
+
+Deliver:
+
+1. Findings (highest risk first)
+   - Title and severity/priority
+   - Evidence (`path:line`)
+   - Reproduction steps or triggering input
+   - Broken expectation/invariant
+2. Edge-case evidence
+   - Preconditions
+   - Observed behavior
+   - Reproducibility notes and nearby variant results
+3. Risk assessment
+   - Impact, likelihood, and scope
+   - Why this matters in system context
+4. Hardening guidance (advice only)
+   - Recommended fix direction
+   - Suggested test coverage to add during remediation
+5. Residual risk
+   - Hypotheses, unknowns, and next validation ideas
+
+## Minimum Coverage
+
+Apply all relevant checks for the selected scope:
+
+- Input validation: empty/null/malformed/unexpected-type handling
+- Boundary behavior: zero/one/min/max/overflow/ordering edges
+- Failure behavior: timeout, retry, partial dependency failure, degraded mode
+- Stateful behavior: idempotency, replay, concurrency, rollback, duplicate processing
+- Observability: actionable errors and logging for failures that would otherwise be silent
+
+## Resources
+
+- `references/architecture-edge-cases.md`: cross-module/system-level edge-case checklist.
+- `references/code-edge-cases.md`: code-level input, boundary, and error-path checklist.

package/discover-edge-cases/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Discover Edge Cases"
+  short_description: "Discover reproducible edge-case risks and coverage gaps"
+  default_prompt: "Use $discover-edge-cases to scan the current diff first (or the full codebase when there is no diff), discard any bias toward code written earlier in the conversation, run $harden-app-security as an adversarial cross-check for code-affecting scope, identify the highest-risk reproducible edge-case findings, validate them with concrete evidence, prioritize the confirmed risks, and report hardening and test recommendations without modifying code."

package/discover-edge-cases/references/architecture-edge-cases.md

@@ -0,0 +1,41 @@
+# Common Architecture-level Edge Cases (Reference List)
+
+## How to use
+- Pick only 2-5 items directly related to the current change; avoid exhaustive scans.
+- If changes involve external dependencies/concurrency/scheduling/messaging, prioritize matching sections.
+
+## Concurrency and synchronization
+- Race conditions: concurrent updates to the same resource cause overwrite/lost updates
+- Deadlock/livelock: inconsistent lock ordering, reentrant lock misuse, or busy-wait loops
+- Visibility/memory consistency: cross-thread state is not synchronized
+- Async task leaks: background tasks not cancelled or cleaned up
+
+## Backpressure and resources
+- Backpressure failure: slow downstream causes upstream queue growth, OOM, or queue saturation
+- Resource starvation: high-priority tasks monopolize resources
+- Connection pool exhaustion: unreleased or delayed-release connections
+- File/socket leaks: exception paths skip close/release
+
+## Distributed systems
+- Network partition/intermittent unreachable state: requires retry/degrade/isolation strategy
+- Retry storms: retry amplification under failure
+- Consistency gaps: stale reads or partial writes
+- Duplicate messages: at-least-once delivery causes duplicate processing
+- Message ordering: reordering/out-of-order events corrupt state
+- Clock skew: time-based ordering/expiration becomes incorrect
+
+## Timeout and cancellation
+- Timeout not propagated: child tasks continue and consume resources
+- Non-reentrant cancellation: retry causes inconsistent state
+- Timeout boundary flapping: unstable behavior near timeout thresholds
+
+## Error handling and rollback
+- Partial success: multi-step writes complete only partially
+- Rollback failure: compensation action fails and leaves inconsistent data
+- Swallowed exceptions: errors are neither surfaced nor logged
+- Missing idempotency: retries create duplicate side effects
+
+## Deployment and versioning
+- Rolling upgrade mismatch: old/new versions run together with inconsistent behavior
+- Config drift: node configurations diverge
+- Hot reload instability: temporary unavailability or state loss during reload