@laitszkin/apollo-toolkit 2.0.0

package/docs-to-voice/scripts/docs_to_voice.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[ERROR] python3 is required." >&2
+  exit 1
+fi
+
+exec python3 "$script_dir/docs_to_voice.py" "$@"

package/docs-to-voice/tests/test_docs_to_voice_api_max_chars.py

@@ -0,0 +1,210 @@
+import http.client
+import unittest
+from unittest.mock import patch
+
+from scripts.docs_to_voice import (
+    DocsToVoiceError,
+    api_text_length_units,
+    discover_api_max_chars,
+    extract_max_chars_from_text,
+    fetch_api_model_max_chars,
+    is_max_chars_disabled,
+    probe_api_max_chars,
+    request_model_studio_audio,
+    split_text_for_tts,
+)
+
+
+class ExtractMaxCharsFromTextTests(unittest.TestCase):
+    def test_extracts_limit_from_range_message(self):
+        message = (
+            "Model Studio TTS request failed (HTTP 400): "
+            "InvalidParameter: Range of input length should be [0, 600]"
+        )
+        self.assertEqual(extract_max_chars_from_text(message), 600)
+
+    def test_extracts_limit_with_comma(self):
+        message = "Maximum input length is 1,200 characters."
+        self.assertEqual(extract_max_chars_from_text(message), 1200)
+
+    def test_extracts_limit_from_chinese_message(self):
+        message = "請求失敗：輸入長度上限為 600 字元"
+        self.assertEqual(extract_max_chars_from_text(message), 600)
+
+    def test_returns_none_for_unrelated_message(self):
+        self.assertIsNone(extract_max_chars_from_text("network timeout"))
+
+
+class MaxCharsDisabledTests(unittest.TestCase):
+    def test_zero_string_disables_chunking(self):
+        self.assertTrue(is_max_chars_disabled("0"))
+
+    def test_non_zero_does_not_disable_chunking(self):
+        self.assertFalse(is_max_chars_disabled("1200"))
+
+
+class ApiTextLengthUnitsTests(unittest.TestCase):
+    def test_counts_chinese_as_two_units(self):
+        self.assertEqual(api_text_length_units("AB測試!"), 7)
+
+    def test_split_text_respects_weighted_units(self):
+        chunks = split_text_for_tts("測" * 301, 600, length_func=api_text_length_units)
+        self.assertEqual(len(chunks), 2)
+        self.assertEqual(chunks[0], "測" * 300)
+        self.assertEqual(chunks[1], "測")
+
+
+class FetchApiModelMaxCharsTests(unittest.TestCase):
+    @patch("scripts.docs_to_voice.fetch_json_payload")
+    def test_fetches_limit_from_model_catalog(self, mock_fetch_json_payload):
+        mock_fetch_json_payload.return_value = {
+            "output": {
+                "total": 1,
+                "models": [
+                    {
+                        "model": "qwen3-tts",
+                        "model_info": {"max_input_tokens": 600},
+                    }
+                ],
+            }
+        }
+
+        result = fetch_api_model_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+        )
+
+        self.assertEqual(result, 600)
+
+    @patch("scripts.docs_to_voice.fetch_json_payload")
+    def test_returns_none_when_catalog_request_fails(self, mock_fetch_json_payload):
+        mock_fetch_json_payload.side_effect = RuntimeError("network error")
+
+        result = fetch_api_model_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+        )
+
+        self.assertIsNone(result)
+
+    @patch("scripts.docs_to_voice.fetch_json_payload")
+    def test_fetches_limit_from_later_page_when_needed(self, mock_fetch_json_payload):
+        mock_fetch_json_payload.side_effect = [
+            {
+                "output": {
+                    "total": 101,
+                    "models": [{"model": "other-model", "model_info": {}}],
+                }
+            },
+            {
+                "output": {
+                    "total": 101,
+                    "models": [
+                        {
+                            "model": "qwen3-tts",
+                            "description": "Range of input length should be [0, 800]",
+                        }
+                    ],
+                }
+            },
+        ]
+
+        result = fetch_api_model_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+        )
+
+        self.assertEqual(result, 800)
+        self.assertEqual(mock_fetch_json_payload.call_count, 2)
+
+
+class ProbeApiMaxCharsTests(unittest.TestCase):
+    @patch("scripts.docs_to_voice.request_model_studio_audio")
+    def test_probe_extracts_limit_from_api_error(self, mock_request_model_studio_audio):
+        mock_request_model_studio_audio.side_effect = DocsToVoiceError(
+            "Model Studio TTS request failed (HTTP 400): "
+            "InvalidParameter: Range of input length should be [0, 600]"
+        )
+
+        result = probe_api_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+            voice="Cherry",
+        )
+
+        self.assertEqual(result, 600)
+
+    @patch("scripts.docs_to_voice.request_model_studio_audio")
+    def test_probe_returns_none_when_probe_request_succeeds(self, mock_request_model_studio_audio):
+        mock_request_model_studio_audio.return_value = {
+            "audio_url": "https://example.com/audio.wav",
+            "audio_data": "",
+            "audio_format": "wav",
+        }
+
+        result = probe_api_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+            voice="Cherry",
+        )
+
+        self.assertIsNone(result)
+
+
+class DiscoverApiMaxCharsTests(unittest.TestCase):
+    @patch("scripts.docs_to_voice.probe_api_max_chars")
+    @patch("scripts.docs_to_voice.fetch_api_model_max_chars")
+    def test_prefers_catalog_limit(self, mock_fetch_api_model_max_chars, mock_probe_api_max_chars):
+        mock_fetch_api_model_max_chars.return_value = 700
+
+        result = discover_api_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+            voice="Cherry",
+        )
+
+        self.assertEqual(result, 700)
+        mock_probe_api_max_chars.assert_not_called()
+
+    @patch("scripts.docs_to_voice.probe_api_max_chars")
+    @patch("scripts.docs_to_voice.fetch_api_model_max_chars")
+    def test_falls_back_to_probe_limit(self, mock_fetch_api_model_max_chars, mock_probe_api_max_chars):
+        mock_fetch_api_model_max_chars.return_value = None
+        mock_probe_api_max_chars.return_value = 600
+
+        result = discover_api_max_chars(
+            api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+            api_key="test-key",
+            model="qwen3-tts",
+            voice="Cherry",
+        )
+
+        self.assertEqual(result, 600)
+        mock_probe_api_max_chars.assert_called_once()
+
+
+class RequestModelStudioAudioTests(unittest.TestCase):
+    @patch("scripts.docs_to_voice.urllib.request.urlopen")
+    def test_wraps_http_client_disconnect_as_user_error(self, mock_urlopen):
+        mock_urlopen.side_effect = http.client.RemoteDisconnected(
+            "Remote end closed connection without response"
+        )
+
+        with self.assertRaisesRegex(DocsToVoiceError, "Remote end closed connection"):
+            request_model_studio_audio(
+                api_endpoint="https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
+                api_key="test-key",
+                model="qwen3-tts",
+                voice="Cherry",
+                text="test",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/docs-to-voice/tests/test_docs_to_voice_sentence_timeline.py

@@ -0,0 +1,115 @@
+import json
+import pathlib
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from scripts.docs_to_voice import (
+    DocsToVoiceError,
+    api_text_length_units,
+    split_text_into_api_sentence_requests,
+    write_sentence_timeline_files,
+)
+
+
+class ApiSentenceRequestTests(unittest.TestCase):
+    def test_builds_one_request_per_sentence_by_default(self):
+        source_text = "第一句。第二句！第三句？"
+        sentences, request_items = split_text_into_api_sentence_requests(
+            source_text=source_text,
+            max_chars=None,
+            length_func=api_text_length_units,
+        )
+
+        self.assertEqual(sentences, ["第一句。", "第二句！", "第三句？"])
+        self.assertEqual([item["sentence_index"] for item in request_items], [0, 1, 2])
+        self.assertEqual([item["text"] for item in request_items], sentences)
+
+    def test_splits_oversized_sentence_and_keeps_sentence_index(self):
+        source_text = "測" * 301
+        sentences, request_items = split_text_into_api_sentence_requests(
+            source_text=source_text,
+            max_chars=600,
+            length_func=api_text_length_units,
+        )
+
+        self.assertEqual(sentences, [source_text])
+        self.assertEqual(len(request_items), 2)
+        self.assertEqual([item["sentence_index"] for item in request_items], [0, 0])
+        self.assertEqual(request_items[0]["text"], "測" * 300)
+        self.assertEqual(request_items[1]["text"], "測")
+
+    def test_raises_when_text_is_empty(self):
+        with self.assertRaises(DocsToVoiceError):
+            split_text_into_api_sentence_requests(
+                source_text="   \n",
+                max_chars=600,
+                length_func=api_text_length_units,
+            )
+
+
+class SentenceTimelineTests(unittest.TestCase):
+    def test_uses_sentence_audio_durations_for_timestamp(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_dir_path = pathlib.Path(temp_dir)
+            audio_path = temp_dir_path / "voice.wav"
+
+            with patch("scripts.docs_to_voice.read_duration_seconds", return_value=2.0):
+                write_sentence_timeline_files(
+                    source_text="甲。乙。",
+                    audio_path=audio_path,
+                    sentence_durations=[1.2, 0.8],
+                    timing_mode_hint="sentence-audio",
+                )
+
+            timeline_json_path = temp_dir_path / "voice.timeline.json"
+            timeline_payload = json.loads(timeline_json_path.read_text(encoding="utf-8"))
+
+            self.assertEqual(timeline_payload["timing_mode"], "sentence-audio")
+            self.assertEqual(timeline_payload["sentences"][0]["start_ms"], 0)
+            self.assertEqual(timeline_payload["sentences"][0]["end_ms"], 1200)
+            self.assertEqual(timeline_payload["sentences"][1]["start_ms"], 1200)
+            self.assertEqual(timeline_payload["sentences"][1]["end_ms"], 2000)
+
+    def test_scales_sentence_duration_to_match_output_duration(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_dir_path = pathlib.Path(temp_dir)
+            audio_path = temp_dir_path / "voice.wav"
+
+            with patch("scripts.docs_to_voice.read_duration_seconds", return_value=4.0):
+                write_sentence_timeline_files(
+                    source_text="甲。乙。",
+                    audio_path=audio_path,
+                    sentence_durations=[1.0, 1.0],
+                    timing_mode_hint="sentence-audio",
+                )
+
+            timeline_json_path = temp_dir_path / "voice.timeline.json"
+            timeline_payload = json.loads(timeline_json_path.read_text(encoding="utf-8"))
+
+            self.assertEqual(timeline_payload["timing_mode"], "sentence-audio")
+            self.assertEqual(timeline_payload["sentences"][0]["end_ms"], 2000)
+            self.assertEqual(timeline_payload["sentences"][1]["end_ms"], 4000)
+
+    def test_falls_back_when_sentence_duration_count_mismatched(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_dir_path = pathlib.Path(temp_dir)
+            audio_path = temp_dir_path / "voice.wav"
+
+            with patch("scripts.docs_to_voice.read_duration_seconds", return_value=2.0):
+                write_sentence_timeline_files(
+                    source_text="甲。乙。",
+                    audio_path=audio_path,
+                    sentence_durations=[2.0],
+                    timing_mode_hint="sentence-audio",
+                )
+
+            timeline_json_path = temp_dir_path / "voice.timeline.json"
+            timeline_payload = json.loads(timeline_json_path.read_text(encoding="utf-8"))
+
+            self.assertEqual(timeline_payload["timing_mode"], "duration-weighted")
+            self.assertEqual(timeline_payload["sentences"][1]["end_ms"], 2000)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/docs-to-voice/tests/test_docs_to_voice_settings.py

@@ -0,0 +1,43 @@
+import os
+import unittest
+
+from scripts.docs_to_voice import resolve_setting
+
+
+class ResolveSettingTests(unittest.TestCase):
+    def setUp(self):
+        self.env_key = "DOCS_TO_VOICE_TEST_SETTING"
+        self.previous = os.environ.get(self.env_key)
+        os.environ.pop(self.env_key, None)
+
+    def tearDown(self):
+        os.environ.pop(self.env_key, None)
+        if self.previous is not None:
+            os.environ[self.env_key] = self.previous
+
+    def test_cli_value_has_highest_priority(self):
+        os.environ[self.env_key] = "env-value"
+        result = resolve_setting("cli-value", self.env_key, {"DOCS_TO_VOICE_TEST_SETTING": "file-value"})
+        self.assertEqual(result, "cli-value")
+
+    def test_env_file_has_priority_over_process_env(self):
+        os.environ[self.env_key] = "env-value"
+        result = resolve_setting(None, self.env_key, {"DOCS_TO_VOICE_TEST_SETTING": "file-value"})
+        self.assertEqual(result, "file-value")
+
+    def test_blank_cli_value_falls_back_to_env_file(self):
+        result = resolve_setting("   ", self.env_key, {"DOCS_TO_VOICE_TEST_SETTING": "file-value"})
+        self.assertEqual(result, "file-value")
+
+    def test_process_env_used_when_env_file_missing(self):
+        os.environ[self.env_key] = "env-value"
+        result = resolve_setting(None, self.env_key, {})
+        self.assertEqual(result, "env-value")
+
+    def test_default_used_when_no_source_available(self):
+        result = resolve_setting(None, self.env_key, {}, "default-value")
+        self.assertEqual(result, "default-value")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/docs-to-voice/tests/test_docs_to_voice_speech_rate.py

@@ -0,0 +1,57 @@
+import unittest
+
+from scripts.docs_to_voice import (
+    DocsToVoiceError,
+    build_atempo_filter_chain,
+    scale_sentence_durations,
+    validate_speech_rate,
+)
+
+
+class ValidateSpeechRateTests(unittest.TestCase):
+    def test_accepts_positive_float(self):
+        self.assertEqual(validate_speech_rate("1.25"), 1.25)
+
+    def test_returns_none_for_blank_value(self):
+        self.assertIsNone(validate_speech_rate("   "))
+
+    def test_rejects_non_positive_value(self):
+        with self.assertRaisesRegex(DocsToVoiceError, "--speech-rate"):
+            validate_speech_rate("0")
+
+    def test_rejects_non_numeric_value(self):
+        with self.assertRaisesRegex(DocsToVoiceError, "--speech-rate"):
+            validate_speech_rate("fast")
+
+    def test_rejects_non_finite_values(self):
+        for value in ("nan", "inf", "-inf"):
+            with self.subTest(value=value):
+                with self.assertRaisesRegex(DocsToVoiceError, "--speech-rate"):
+                    validate_speech_rate(value)
+
+
+class BuildAtempoFilterChainTests(unittest.TestCase):
+    def test_builds_single_stage_filter(self):
+        self.assertEqual(build_atempo_filter_chain(1.25), "atempo=1.25")
+
+    def test_builds_multi_stage_filter_for_high_rate(self):
+        self.assertEqual(build_atempo_filter_chain(4.0), "atempo=2.0,atempo=2.0")
+
+    def test_builds_multi_stage_filter_for_low_rate(self):
+        self.assertEqual(build_atempo_filter_chain(0.25), "atempo=0.5,atempo=0.5")
+
+
+class ScaleSentenceDurationsTests(unittest.TestCase):
+    def test_scales_all_sentence_durations(self):
+        self.assertEqual(
+            scale_sentence_durations([1.2, 0.8], 2.0),
+            [0.6, 0.4],
+        )
+
+    def test_returns_original_when_rate_is_one(self):
+        values = [1.2, 0.8]
+        self.assertEqual(scale_sentence_durations(values, 1.0), values)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/enhance-existing-features/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [v0.2.0] - 2026-02-25
+
+### Changed
+- Replaced planning flow with conditional specs workflow (`spec.md` / `tasks.md` / `checklist.md`).
+- Clarified specs trigger scope: high complexity, critical module, or cross-module changes.
+- Added explicit rule that test coverage is required even when specs are not used.
+
+### Added
+- Added `scripts/create-specs` for generating specs into `docs/plans/{YYYY-MM-DD}_{change_name}/`.
+- Added reusable templates under `references/templates/`.
+
+## [v0.1.2] - 2026-02-12
+
+### Changed
+- Tightened multi-module planning workflow to require explicit user approval before implementation.
+- Updated usage docs and agent metadata for approval gating clarity.
+
+## [v0.1.1] - 2026-02-12
+
+### Added
+- Added built-in planning script and planning template for cross-module feature changes.
+
+### Changed
+- Updated the skill workflow to require planning before implementation when a request spans multiple modules.
+- Updated skill metadata and usage docs to reflect planning-first behavior for multi-module work.
+- Refreshed repository introduction wording for clearer agent-skill positioning.
+
+## [v0.1.0] - 2026-02-07
+
+### Added
+- Initial release of the `enhance-existing-features` skill for dependency mapping, authoritative doc verification, focused implementation, and test updates in brownfield codebases.

package/enhance-existing-features/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+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/enhance-existing-features/README.md

@@ -0,0 +1,54 @@
+# enhance-existing-features
+
+A brownfield feature-extension skill: map dependencies first, decide whether shared specs are required, then implement the approved change with risk-driven hardening tests.
+
+## Core capabilities
+
+- Explores dependencies and data flow before deciding how to change the system.
+- Uses `generate-spec` whenever the change is high-complexity, touches a critical module, or crosses module boundaries.
+- Requires explicit approval before coding when specs are generated.
+- Still requires meaningful tests even when specs are skipped.
+- Keeps brownfield changes focused and traceable.
+
+## Repository layout
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+└── references/
+    ├── unit-tests.md
+    ├── property-based-tests.md
+    ├── integration-tests.md
+    └── e2e-tests.md
+```
+
+## Workflow summary
+
+1. Explore the existing codebase and affected logic chain first.
+2. Trigger `generate-spec` only when the change is high complexity, hits a critical module, or crosses module boundaries.
+3. Wait for explicit approval if planning docs were generated.
+4. Implement the smallest safe brownfield change.
+5. Run risk-driven tests and backfill planning docs when they exist.
+
+## Test requirements
+
+- Unit: changed logic, boundaries, failure paths.
+- Regression: bug-prone or high-risk behavior that must not silently return.
+- Property-based: mandatory for business logic unless concrete `N/A` is recorded.
+- Integration: user-critical logic chain across layers/modules.
+- E2E: affected key user-visible path when the risk justifies it.
+- Adversarial: abuse paths, malformed inputs, privilege issues, replay, concurrency, and edge combinations when relevant.
+
+If E2E is not feasible, replace it with stronger integration coverage and record the reason.
+
+## References
+
+- Shared planning workflow: `generate-spec`
+- Unit testing guide: `references/unit-tests.md`
+- Property-based testing guide: `references/property-based-tests.md`
+- Integration testing guide: `references/integration-tests.md`
+- E2E testing guide: `references/e2e-tests.md`

package/enhance-existing-features/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: enhance-existing-features
+description: >-
+  Build and extend brownfield features in an existing codebase. Always explore
+  the codebase first, then decide from the user's requested change whether
+  specs (`spec.md`/`tasks.md`/`checklist.md`) are required before coding. When
+  specs are required, depend on `generate-spec` for the shared planning,
+  clarification, approval, and backfill workflow. Even when specs are not
+  required, still add and run related tests for
+  unit/property-based/user-critical integration chain/E2E coverage. 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.
+---
+
+# Enhance Existing Features
+
+## Dependencies
+
+- Required: `generate-spec` for shared planning docs when spec-trigger conditions are met.
+- Conditional: none.
+- Optional: none.
+- Fallback: If specs are required and `generate-spec` is unavailable, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Explore the existing codebase first and verify the latest authoritative docs for the involved stack or integrations.
+- Execution: Decide whether specs are required from the actual change surface, run `generate-spec` when needed, then implement minimally.
+- Quality: Add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
+- Output: Keep implementation and any planning artifacts traceable, updated, and aligned with actual completion results.
+
+## Overview
+
+Safely extend brownfield systems by exploring the existing codebase first, using the user's requested change plus discovered impact to decide whether specs are needed, then following a consistent implementation and testing workflow with minimal, well-validated changes.
+
+## Workflow
+
+### 1) Explore codebase first
+
+- Read the relevant existing code before deciding process or editing anything.
+- Locate entrypoints, configuration, and primary data flow.
+- Trace module relationships (imports, call graph, shared models, side effects).
+- Identify integration points (DB, RPC, external APIs, queues, filesystems).
+- Identify user-critical logic chains affected by the change.
+- Summarize findings and the likely change surface before editing.
+
+### 2) Decide whether specs are required from the requested change
+
+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
+
+If triggered:
+- Run `$generate-spec` and follow its workflow completely.
+- Use it to create or update `docs/plans/{YYYY-MM-DD}_{change_name}/spec.md`, `tasks.md`, and `checklist.md`.
+- Ensure planned behaviors and edge cases cover external dependency states, abuse/adversarial paths, and any relevant authorization/idempotency/concurrency/data-integrity risks.
+- If users answer clarification questions, update the planning docs and obtain explicit approval again before implementation.
+- Do not modify implementation code before approval.
+
+If not triggered:
+- Continue directly with the same downstream workflow below.
+
+### 3) Verify latest authoritative docs
+
+- Identify the tech stack, libraries, and external dependencies involved.
+- Use official documentation as the source of truth.
+- Prefer Context7 for framework/library APIs; use web for latest official docs.
+- If required docs are private or missing, request access or user-provided references.
+
+### 4) Implement the feature
+
+- Reuse existing patterns and abstractions; avoid over-engineering.
+- Keep changes focused and minimal; preserve current behavior unless required.
+- Follow project conventions (naming, linting, formatting, configuration).
+- Update environment examples only when new inputs are required.
+
+### 5) Testing coverage (required with or without specs)
+
+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.
+- 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
+
+- If specs were used, backfill `tasks.md` and `checklist.md` through `$generate-spec` workflow based on actual completion and test outcomes.
+- 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
+
+- Keep the solution minimal and executable.
+- 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.
+- 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/unit-tests.md`: unit testing guidance.
+- `references/property-based-tests.md`: property-based testing guidance.
+- `references/integration-tests.md`: integration testing guidance.
+- `references/e2e-tests.md`: E2E decision and design guidance.

package/enhance-existing-features/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "enhance-existing-features"
+  short_description: "Extend brownfield features with conditional generate-spec planning and risk-driven tests"
+  default_prompt: "Use $enhance-existing-features to extend a brownfield feature: map the affected code and dependencies first, decide whether the change is high complexity / critical module / cross-module, run $generate-spec when specs are required, wait for explicit approval before coding, and always add risk-driven tests plus clear N/A reasons when a category truly does not apply."