codex-subagent-router/docs/development.md

Development and validation

Ownership

The skill owns task routing, authorization checks, context contracts, lifecycle and evidence. The optional global prompt owns general engineering constraints and references the skill. The repository AGENTS.md governs contributors; it is not the installable global prompt.

The bundled validator validates evidence structure only. It cannot authenticate a child ID, prove an observed model, enforce a sandbox, or judge an artifact's correctness.

Test layers

1. Unit tests exercise evidence parsing and rejection of malformed claims, legacy compatibility, and installer preservation/rollback safety.
2. Repository checks verify packaged resources, relative links, UI metadata, and frontmatter essentials.
3. Static scenarios in behavior-scenarios.md cover trigger/management decisions.
4. Actual host forward tests are separate and require authorized real tasks. Record requested model, observed identity (or unknown), completion, tool results, parent acceptance and actual usage if exposed. Never report synthetic cases as live rollouts.

Use Python 3.9+ and the standard library. The optional upstream skill-creator quick_validate.py requires PyYAML; if missing, report the missing dependency rather than substituting an unreported result.

Compatibility with other skills

Do not automatically rewrite unrelated skills. Older orchestration skills may assume forked workspaces, a close tool, or a Sol-only parent. Resolve conflicting applicable instructions according to host precedence and identify the exact remaining gate. For a coordinated migration, explicitly include those files and their project-specific requirements.

Installing this repository does not change config.toml, the selected model, other skills or active session state. Prompt defaults cannot override host restrictions.

Future measurements

Compare accepted tasks of similar shape, including parent work and retries. Track only observable latency/usage; unknown remains unknown. Expand defaults based on repeated evidence, not model participation targets.