repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(ultra): expose workflow tool schema design

c0bcabd7790dd1f21972999b774c10f9f9d7a9c5

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/specs/2026-07-17-ultra-tool-schema-design.md

Added
new file mode 100644
1 +# Ultra Tool Schema Design
3 +## Problem
5 +The `workflow` tool exposes inline `spec` as unrestricted `any`, while the runtime requires `WorkflowSpecSchema`.
6 +Agents therefore guess the contract, fail validation before progress begins, then inspect Ultra source code to recover.
8 +## Design
10 +Use the existing exported `WorkflowSpecSchema` as the tool parameter schema for inline `spec`.
11 +Keep runtime parsing unchanged as the trust-boundary validation.
12 +Do not duplicate the schema in descriptions or skill prose.
14 +Add a harness regression proving the registered inline `spec` schema structurally equals the exported `WorkflowSpecSchema`.
15 +Keep the bundled authoring skill and runtime/tool contracts semantically synchronized through the subtree instruction in `extensions/ultra/AGENTS.md`; only semantic contract changes require affected surfaces to change.
17 +## Files
19 +- `extensions/ultra/index.ts`: expose `WorkflowSpecSchema` through the `workflow` tool contract.
20 +- `extensions/ultra/__tests__/harness.test.ts`: test the registered contract.
21 +- `extensions/ultra/AGENTS.md`: persist the semantic lockstep rule.
23 +## Verification
25 +Run the Ultra harness test, Ultra test suite, and repository checks through `mise`.

extensions/ultra/AGENTS.md

Added
new file mode 100644
1 +# Ultra
3 +- Keep runtime/tool contracts and bundled skill guidance semantically synchronized; when either contract changes, update affected surfaces and lockstep tests.