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.
# 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.