|
| 1 | +# Yemot Telephony Skill Implementation Plan |
| 2 | + |
| 3 | +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Checked items are complete; unchecked items remain pending. |
| 4 | +
|
| 5 | +**Goal:** Build, validate and publish-ready package a comprehensive Yemot Hamashiach telephony skill while keeping the website integration to one concise catalog card. |
| 6 | + |
| 7 | +**Architecture:** A lean `SKILL.md` routes agents to curated references or readable generated Markdown topics. Refresh, search, validation and packaging scripts make the large external documentation set maintainable without loading it all into context. |
| 8 | + |
| 9 | +**Tech Stack:** Markdown, YAML, Python 3 standard library, PowerShell 7, existing Python/markdown2 site builder, GitHub Actions. |
| 10 | + |
| 11 | +## Current Implementation Status (2026-07-10) |
| 12 | + |
| 13 | +- The complete readable snapshot is implemented and validated: 157 topics, 607 selected posts and 158 Markdown documents. |
| 14 | +- `source-manifest.json` is intentionally retained as machine-readable provenance and coverage data. The refresher generates it, the validator requires it, and the release workflow validates it. |
| 15 | +- The public display name is `ימות המשיח — מערכות טלפוניות`; the stable technical slug remains `yemot-telephony`. |
| 16 | +- The website remains a compact catalog. Its `סקילים` section appears first and exposes only ZIP download and source actions. |
| 17 | +- The initial release target is `yemot-telephony-v0.1.0`, reflecting an early-development SemVer release. |
| 18 | +- Repository publication status is authoritative in GitHub history; the final unchecked items below intentionally preserve the pre-publication gate recorded by this plan. |
| 19 | + |
| 20 | +## Global Constraints |
| 21 | + |
| 22 | +- Put the skill at `skills/yemot-telephony/`. |
| 23 | +- Keep detailed documentation inside the skill, not on the website. |
| 24 | +- Use only official Yemot-hosted sources as authoritative documentation; label community replies. |
| 25 | +- Do not store live credentials or personal data. |
| 26 | +- Perform repository integration and release actions only after validation. |
| 27 | + |
| 28 | +--- |
| 29 | + |
| 30 | +### Task 1: Build the documentation corpus pipeline |
| 31 | + |
| 32 | +**Files:** |
| 33 | +- Create: `skills/yemot-telephony/scripts/refresh_docs.py` |
| 34 | +- Create: `skills/yemot-telephony/scripts/search_docs.py` |
| 35 | +- Create: `skills/yemot-telephony/scripts/validate_snapshot.py` |
| 36 | +- Create: `skills/yemot-telephony/tests/test_scripts.py` |
| 37 | + |
| 38 | +**Interfaces:** |
| 39 | +- `refresh_docs.py --output-dir PATH` produces `snapshot/*.md`, `source-manifest.json` and `source-index.md`. |
| 40 | +- `search_docs.py QUERY --snapshot-dir PATH --limit N` prints ranked source-backed Markdown matches with file and source URLs. |
| 41 | +- `validate_snapshot.py --references-dir PATH` exits nonzero for invalid or incomplete snapshots. |
| 42 | + |
| 43 | +- [x] Write tests for normalization, post-link resolution, ranking, redaction-safe output and schema validation. |
| 44 | +- [x] Run `python -m unittest skills/yemot-telephony/tests/test_scripts.py -v` and confirm the missing modules fail. |
| 45 | +- [x] Implement the three standard-library scripts with retry, pagination, deterministic Markdown rendering, bounded file sizes, atomic output and Netfree-aware errors. |
| 46 | +- [x] Re-run the unit tests and confirm they pass. |
| 47 | + |
| 48 | +### Task 2: Generate and audit the complete snapshot |
| 49 | + |
| 50 | +**Files:** |
| 51 | +- Create: `skills/yemot-telephony/references/snapshot/*.md` |
| 52 | +- Create: `skills/yemot-telephony/references/source-manifest.json` |
| 53 | +- Create: `skills/yemot-telephony/references/source-index.md` |
| 54 | + |
| 55 | +**Interfaces:** |
| 56 | +- Every topic document contains stable topic metadata and post sections with author/authority labels, timestamps, source URLs and complete normalized content. Files above the configured limit are split at Markdown boundaries. |
| 57 | + |
| 58 | +- [x] Run the refresher against the official forum index, API topic and API forum. |
| 59 | +- [x] Retry or explicitly record unresolved and inaccessible source links. |
| 60 | +- [x] Validate minimum topic/post coverage, unique record IDs, non-empty content and HTTPS source URLs. |
| 61 | +- [x] Search representative terms: `type=api`, `recording_and_entering_data`, `CreateSipAccount`, `X-Yemot-CallID`, `queue_api_send` and `M1000`. |
| 62 | + |
| 63 | +### Task 3: Author the skill and curated guidance |
| 64 | + |
| 65 | +**Files:** |
| 66 | +- Create: `skills/yemot-telephony/SKILL.md` |
| 67 | +- Create: `skills/yemot-telephony/agents/openai.yaml` |
| 68 | +- Create: `skills/yemot-telephony/references/concepts-and-workflow.md` |
| 69 | +- Create: `skills/yemot-telephony/references/api-and-integrations.md` |
| 70 | +- Create: `skills/yemot-telephony/references/practical-recipes.md` |
| 71 | + |
| 72 | +**Interfaces:** |
| 73 | +- `SKILL.md` tells agents exactly which reference or search command to use for each task class. |
| 74 | +- Curated files contain stable mental models, security practices, implementation sequences and concise tested examples; parameter exhaustiveness remains in the corpus. |
| 75 | + |
| 76 | +- [x] Initialize the skill with the official `init_skill.py` and generated UI strings. |
| 77 | +- [x] Replace scaffold placeholders with concise imperative instructions and source hierarchy rules. |
| 78 | +- [x] Add practical examples for a basic menu, API extension, management API call and SIP/WebRTC setup without real credentials. |
| 79 | +- [x] Run `quick_validate.py` and scan for placeholders, duplicated guidance and unsafe example secrets. |
| 80 | + |
| 81 | +### Task 4: Add minimal catalog and release packaging |
| 82 | + |
| 83 | +**Files:** |
| 84 | +- Modify: `README.md` |
| 85 | +- Modify: `build.py` |
| 86 | +- Modify: `index.html` (generated) |
| 87 | +- Create: `scripts/package-yemot-telephony.ps1` |
| 88 | +- Create: `.github/workflows/release-yemot-telephony.yml` |
| 89 | +- Create: `tests/test_build.py` |
| 90 | + |
| 91 | +**Interfaces:** |
| 92 | +- A README section containing `סקיל` is rendered as a skill card with latest-release download and source actions. |
| 93 | +- `scripts/package-yemot-telephony.ps1 -OutputPath PATH` creates `yemot-telephony.zip` with a top-level skill folder. |
| 94 | + |
| 95 | +- [x] Write a build test proving the card exposes exactly download and source actions. |
| 96 | +- [x] Extend the builder with a dedicated `skill` type and run the test to green. |
| 97 | +- [x] Add the concise README entry and regenerate `index.html` with `python build.py`. |
| 98 | +- [x] Add deterministic packaging and tag/manual GitHub Actions workflow. |
| 99 | +- [x] Build the archive locally and inspect its file list. |
| 100 | + |
| 101 | +### Task 5: Final verification and repository integration |
| 102 | + |
| 103 | +**Files:** |
| 104 | +- Verify all files changed by Tasks 1-4. |
| 105 | + |
| 106 | +**Interfaces:** |
| 107 | +- The full verification command set is reproducible from a clean checkout. |
| 108 | + |
| 109 | +- [x] Run all Python unit tests, corpus validation, skill validation and the site build. |
| 110 | +- [x] Confirm `git diff --check` and scan the final diff for secrets and unrelated changes. |
| 111 | +- [x] Confirm the website contains no detailed Yemot documentation. |
| 112 | +- [ ] Commit the complete focused change only after every check passes. |
| 113 | +- [ ] Push the feature branch and create a release/tag only if the release asset workflow and repository state are ready. |
0 commit comments