---

name: repo-development description: "Guide Observal repository-wide setup, lint/test selection, contributor policy, release/compliance scripts, and PR readiness workflow." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Observal Repo Development Router

Use this sub-skill when a task is about repository-wide contributor operations rather than one product layer: local setup, Make targets, choosing lint and test commands, pre-commit/SPDX/license policy, AI contribution policy, changelog and documentation updates, conventional commits, release/compliance scripts, safe use of development scripts, or the final PR review checklist.

Do not use this sub-skill as the primary guide for detailed implementation inside one layer. Route detailed Typer command work to cli, FastAPI/data/migration work to server, harness registry/adapters/hooks/parsers/session delivery to harness-telemetry, and Vite/React/TanStack Router frontend work to web. Use this sub-skill to coordinate cross-cutting checks and contributor obligations around those changes.

Route the request

• First-time setup, local development loop, rebuild target choice, branch/commit/PR workflow, changelog/docs obligations: read references/development-workflow.md.
• Choosing focused tests, avoiding unnecessary Docker/E2E runs, pytest patterns, ruff/pre-commit/SPDX expectations: read references/testing-and-quality.md.
• Make target inventory, repository scripts, release preparation, license/SBOM/VEX/compliance tooling, live-data seeders, and script safety levels: read references/repo-scripts.md.
• Install/import, CLI/API, config, optional dependency, telemetry/harness, Playwright, release, migration, pre-commit, or workflow failures: read references/troubleshooting.md.

Non-negotiable contributor rules

1. Start from the smallest owning sub-skill for code changes, then return here for repository-wide checks.
2. Keep tests hermetic by default. Docker is for the local stack, Playwright/E2E, live integration scripts, and manual service validation; it is not required for normal Python unit tests.
3. Any CLI command add/remove/rename/flag change must update bundled CLI skill files and regenerate the auto-generated Observal command reference.
4. Any user-facing behavior change needs a changelog entry under [Unreleased]; frontend UI changes also need screenshots in the PR body.
5. New source files need SPDX copyright and Apache-2.0 license headers. Let hooks update committer copyright lines rather than hand-editing bulk headers unless doing a dedicated license repair.
6. Follow Conventional Commits (feat, fix, docs, refactor, test, build, ci, chore with optional scope). Keep subject lines short, imperative, and without trailing periods.
7. AI-assisted PRs are allowed only with accountable human direction, full human diff review, local execution of appropriate checks, and explicit AI tool/version disclosure. Unattended autonomous submissions are not acceptable.
8. Never commit private harness/editor directories or generated local worktrees such as .claude/, .kiro/, .cursor/, .gemini/, .opencode/, .copilot/, .vscode/, .worktrees/, or their companion instruction files.

Fast repo inspection

From the repository root, run this bundled read-only helper before choosing a broad workflow:

python skills/disco/observal/sub-skills/repo-development/scripts/inspect_observal_repo.py --repo-root . --pretty

Expected signal: JSON containing repository markers, package versions, Make targets, test layout counts, selected evidence-file summaries, and script summaries. The helper should not write files, call the network, invoke Docker, or expose absolute local checkout paths.

Default work loop

1. Identify the owning implementation layer and the user-visible behavior being changed.
2. Use the implementation owner for code design, then use this sub-skill to choose focused tests, docs/changelog updates, and policy checks.
3. Run the narrowest safe checks first, then broaden to make test, make lint, and make check when the diff is PR-ready or touches cross-cutting policy/build files.
4. If a script can mutate files, call a preview/dry-run mode first when available and inspect the diff before committing.
5. Before handoff, state what was tested, what was intentionally not tested, whether Docker/E2E was needed, and any remaining policy or reviewer questions.