srs-develop

# SRS and Oryx Development ## Core Principle **Code and documents are the only truth.** Issue descriptions may be inaccurate. Pull requests may be misleading. Feature descriptions may be insufficient. Always ground your understanding in the actual source code and project documentation. Documents capture design intent, architecture rationale, and complex background that code alone cannot express — they are another form of code. When code and documents conflict, investigate rather than assume one is wrong. ## Critical Rule: No Sensitive Information in Public Repositories 🔒 **SECURITY CRITICAL. SRS, Oryx, proxy, State Threads, website, and dev-docker are public repositories.** Anything written there is published permanently, so never write sensitive information into code, comments, docs, skills, scripts, commit messages, or pull request and issue text: - Secrets, keys, tokens, passwords, and credentials. - Personal information, account names, and private repository names. - Local paths, host names, and host aliases. Environment-specific values belong to the user: - Read them from environment variables or user-configured tools such as `gh` and `ssh` config, and never copy their values into the project. - When a value is needed and not set, ask the user to set it up. - Document only the variable name, with a placeholder that matches it, such as `<srs-test-windows-host>` for `SRS_TEST_WINDOWS_HOST`. ## Critical Rule: Never Push ⚠️ **Never run `git push` unless the user explicitly asks to push.** Committing or picking to a branch means the local branch only. ## Critical Rule: Minimal AI Skill Changes ⚠️ **Keep every AI skill change as minimal as possible.** The maintainer reviews every line and word, so change only what the task requires. ## Critical Rule: Comments Only for Hidden Context ⚠️ **Write a comment only when it gives background the code cannot show**, such as a protocol quirk, a past bug, a platform limitation, or why the obvious approach was not used. - Never write a comment that repeats what the code does or names. - New, self-explanatory code needs no comment. - No plan IDs, task step names, or process history in comments. - When unsure, leave the comment out. ## Independent Implementation from a Reference PR When reimplementing a fix instead of adopting a specific pull request as-is — most often a "fixes"/"resolves" PR whose implementation is rejected — read only its problem description and discussion to understand what is broken. Do not open, re-read, or pattern-match its diff while designing or writing the fix. Design and implement from the current codebase and the problem statement alone. ## Skill Dependencies - `skills/internal-docs-for-srs/SKILL.md` — Route and load project documentation. This skill remains responsible for the development workflow and final result. - `skills/internal-codemap-for-srs/SKILL.md` — Route code navigation and verification to the relevant server map. This skill remains responsible for the development workflow and final result. - `skills/internal-audit-for-srs/SKILL.md` — Audit a change in a fresh subagent that reads the code before the commit message and the tests; Review a PR and Scan PRs run it on the change. This skill remains responsible for the review and final result. - `skills/internal-obs-control/SKILL.md` — Drive isolated OBS instances for the OBS test scripts. - `skills/internal-chrome-control/SKILL.md` — Drive a headless Chrome or Edge for the Chrome test scripts: WHIP, WHEP, HTTP-FLV, HTTP-TS and HLS with `getStats()` samples. - `skills/internal-perf-for-srs/SKILL.md` — Run an SRS performance round: load tool, profiles, ranked bottlenecks and reports. This skill remains responsible for the code changes and their checks. ## Cross-Component Verification For every standalone SRS runtime code change in either the Go proxy or C++ media server, run the complete bundled suite in `references/integration-tests.md`. - Run it in addition to module-specific unit, black-box, protocol E2E, sanitizer, or benchmark verification. - Apply it during development, bug fixing, and pull-request review. - Do not treat the `proxy-*` script names as limiting the suite to proxy changes. - Pick the tier in its Verification Tiers by trigger, never by expected runtime; "run all tests" and backports require Full. ## Test-Driven Development TDD is the principle for every task that touches code, in every workflow: bug fix, feature, enhancement, refactor, or review. Load `references/testable-code.md` and follow its three steps in order, never skipped or merged: 1. Tests first. 2. Refactor for testability. 3. Implement and make every test pass. These rules override any default behavior. When a task only runs tests and changes no code, such as "run all ST tests", still load `references/testable-code.md` and follow its Test platforms and Run tests in a subagent sections. ## Skill Script Language Use **Bash** for skill-owned automation and AI test scripts, including regression helpers. - Keep them compatible with macOS `/bin/bash` 3.2. - Do not create or run Python scripts, inline Python, or Python validation helpers unless the user explicitly requests Python. - Use shell utilities such as `curl` and `jq` for HTTP and JSON work; check required commands before running the test. - The `skills/internal-obs-control` scripts are an approved exception: they use stdlib Python 3.9+. The `srs-develop` test scripts calling them stay Bash 3.2 compatible. - The `skills/internal-chrome-control` scripts are an approved exception: they use Node.js 22.12+ and `puppeteer-core` pinned in their lockfile. The `srs-develop` test scripts calling them stay Bash 3.2 compatible. ## Build and Test in Place - Build and run tests in the current checkout with `make` and the test command; `make` rebuilds what changed. - Do not copy the tree to a temporary directory, or delete build outputs to force a rebuild. - When a test really needs a temporary directory, use a fixed path such as `/tmp/srs-<topic>`. - Remove it by that literal path, never by a variable such as `rm -rf "$dir"`. ## Version and Changelog Whenever a task bumps a version or adds a changelog entry, load `references/version-and-changelog.md` and follow it. - Apply this in every workflow, not only Review a PR: bug fixes and feature work reach a version bump too. - The rules do not change with the routed task. ## Path Resolution - Use the current working directory as the project root. Do not search parent directories or discover alternate repository roots. - For Oryx, use the project-root-relative `oryx/` path through `git -C` while keeping the current working directory unchanged. The path may be a directory or a symlink to the user's preferred checkout. If it is unavailable, ask the user to make the Oryx checkout available there; do not create it automatically, resolve the symlink, or search for another checkout. - For Dev Docker, use the project-root-relative `dev-docker/` path through `git -C` while keeping the current working directory unchanged. The path may be a directory or a symlink to the user's preferred checkout. If it is unavailable, ask the user to make the Dev Docker checkout available there; do not create it automatically, resolve the symlink, or search for another checkout. - For State Threads, use the project-root-relative `state-threads/` path through `git -C` while keeping the current working directory unchanged. The path may be a directory or a symlink to the user's preferred checkout. If it is unavailable, ask the user to make the State Threads checkout available there; do not create it automatically, resolve the symlink, or search for another checkout. - Resolve bundled paths beginning with `references/`, `scripts/`, `assets/`, or `agents/` relative to the directory containing this `SKILL.md`, not the current working directory. - Resolve repository paths such as `trunk/`, `internal/`, `cmd/`, or `skills/` relative to the current working directory. - Use the currently invoked skill directory. Do not search for alternate copies under tool-specific directories such as `.agents/`, `.kiro/`, or `.claude/`. - Before reporting a routed file as missing, check its fully resolved path directly. ## Git Worktree Create a git worktree only when the user asks, or when Review a PR starts on an SRS pull request. Put it next to the SRS checkout and name it `srs-<topic>`, for example `~/projects/srs-pr-4757` for `~/projects/srs`, so relative symlinks such as `oryx/` keep working. Copy `trunk/objs/Platform-*/3rdparty` from the SRS checkout into the worktree, so `./configure` reuses the built third-party libraries. Do not copy the rest of `objs`, or `make` keeps objects built from the other checkout. Skip the copy when the worktree changes `trunk/3rdparty/`. ## Git Workflow Apply these rules whenever a task produces a commit: - Identify the owning repository before inspecting or committing staged changes. Use the current repository for SRS and skills, and `git -C` with the project-root-relative path for the other repositories: - `git -C oryx/` for Oryx - `git -C dev-docker/` for Dev Docker - `git -C state-threads/` for State Threads - `git -C website/` for the website - Never run `git add`; the user stages the files they approve. The exception is a resolved conflict in a merge or cherry-pick the user asked for. - Never run `git push` unless the user explicitly asks. - Commit only when the user explicitly asks. Asking for a step that makes a commit, such as a merge or a cherry-pick, asks for that commit. - After a cherry-pick to another branch, such as a release branch, audit the new commit with `internal-audit-for-srs` before reporting it, and report its findings with the pick. - Before committing, run the owning repository's staged diff, understand every staged change, and write an appropriate title and description. Do not include staged changes from another repository in the same commit. - Prefix the commit title with the tool that made the changes: `OpenClaw:`, `Claude:`, `Codex:`, or `Kiro:`. - If Claude made changes, use this commit message format. End it with the co-author line the Claude Code harness gives; it names the current model, so do not hard-code one: ``` Commit title. Commit description. --------- <co-author line from the harness> ``` - If Codex made changes, use this exact commit message format: ``` Commit title. Commit description. --------- Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com> ``` - If Kiro made changes, use the same title and description, with no fixed trailer. ## Task Router ⚠️ **MANDATORY — Always execute this step first.** Never skip the Task Router. Never jump directly to a task. Every request must be routed through this router before any work begins. Route the user's request to exactly ONE task type. Follow that task only. Do not combine tasks. Choose exactly one supported task: - **Develop Code** — Use for any planned SRS, Oryx, Dev Docker, project-documentation, or skill change. This workflow routes development to the supported Go proxy, SRS player, Dev Docker, or Oryx service and keeps unsupported server work out of scope. → [Develop Code workflow](references/develop-code.md) - **Scan Issues** — Use for a read-only scan of recently active open SRS or Oryx issues that may need attention. Select exactly one repository and compare issues with that project's latest authorized Truth Records without changing GitHub. → [Scan Issues workflow](references/scan-issues.md) - **Scan PRs** — Use for a read-only assessment of a specified SRS or Oryx pull request, or the single most recently updated open pull request in one selected repository. Examine the complete discussion, diff, reviews, and checks without modifying the pull request. → [Scan PRs workflow](references/scan-prs.md) - **Fix a Bug** — Use when an SRS or Oryx issue reports broken, unexpected, unsafe, or otherwise incorrect behavior and may require investigation or a maintenance fix. Verify the report, pause for maintainer approval at Truth Record boundaries, perform only the approved update, and record the final result in the selected project's record. → [Fix a Bug workflow](references/fix-a-bug.md) - **Learn Code** — Use when the user wants an explanation of existing SRS or Oryx implementation, architecture, control flow, or behavior without project changes. Route to the smallest relevant documentation and code map, reconcile them, and answer with focused source references. → [Learn Code workflow](references/learn-code.md) - **Review a PR** — Use for the maintainer's integration workflow after SRS or Oryx changes are already present locally. Select one repository, survey the branch relative to its actual base, correct stale navigation docs, then apply the selected project's version and changelog rules when required. → [Review a PR workflow](references/review-a-pr.md) - **Performance** — Use for an SRS or Go proxy performance, benchmark, load test or profile task: measure SRS or the proxy under many simulated clients, profile it, rank the bottlenecks, fix the top one, or write a performance report. A round is started by hand; an SRS version bump asks the user whether to run one. → [internal-perf-for-srs](../internal-perf-for-srs/SKILL.md) **If the routed task is not yet supported**, stop and tell the user: - What task type you routed to - That this task type is not supported yet - That support will be added in the future Do NOT attempt unsupported tasks. For every task, identify SRS or Oryx before loading a workflow. If the product is ambiguous and the choice changes the repository, issue tracker, code map, or verification, ask the user to clarify. Do not merge SRS and Oryx work unless evidence shows one task crosses the product boundary.