# dynamic-extension builder guidance

- Own one task-specific Pi extension under its `workingCopyPath`; dynamic extensions remain agent-owned until deliberate human promotion.
- Follow brief authority and applicable instructions; inspect relevant sources before editing.
- Search catalog before deciding whether to reuse, copy, improve, or create.
- Read relevant candidate README files when present.
- Keep `manifest.json` with a safe kebab-case `name` and nonempty `description`; optional metadata may describe topic, scope, tags, capabilities, executables, overrides, budgets.
- Provide readable regular `index.ts` exporting a Pi extension; do not introduce symlinks or override Ultra orchestration tools.
- Declare intentional built-in tool collisions with exact qualified `overrides`, e.g. `tool:read`.
- Tests, README, packages, benchmarks, logging, and other implementation details are agent choices, not publication requirements.
- Use native APIs when practical; avoid unexpected side effects during loading.
- Call `validate_dynamic_extension` for fast feedback, then inspect every diagnostic.
- Pi loading and authored tests run within a watchdog; their failures are reported but do not block structurally safe publication.
- Tool ownership checks cover names registered during the bounded load and session start; late registrations or a failed load cannot be proven safe by preflight.
- Repair load/test failures before asking a consumer to use the published revision; never present publication or attestation as proof of quality.
- Create and copy each return a unique editable `workingCopyPath`; neither replaces earlier copies.
- A failed, aborted, or stale working copy remains available for repair; after `stale_base`, copy current state and reconcile intent manually.
- Successful publication advances only that working copy's base revision; edit and validate it again without copying.
- Validation returns a bounded handoff with status, name, `workingCopyPath`, diagnostic codes, and next actions; full diagnostics live in tool details.
- Return `workingCopyPath` and status even when blocked; workflow completion preserves working copies and builder state for recovery.
- Content hashes prevent conflicting edits; historical validator metadata never expires an extension.
- Existing snapshots remain unchanged; promotion into a repository extension requires human approval.