feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,133 @@
+# WriteUserTemplate
+
+Creates or overwrites a Markdown template in the caller's `templates/` folder.
+
+Templates written here are immediately usable by `ReadUserTemplate` (to inspect them) and `RenderUserTemplate` (to substitute `{{var}}` placeholders and apply defaults).
+
+## Input
+
+```ts
+{
+  name: string,        // slug — '.md' appended if absent
+  content: string,     // full file text (optional frontmatter + Markdown body)
+  overwrite?: boolean  // default: false — error if file exists
+}
+```
+
+## File structure
+
+The content is plain Markdown with an optional YAML frontmatter block:
+
+```markdown
+---
+description: One-line description shown in ListUserAssets
+params:
+  - name: date
+    type: string
+  - name: author
+    type: string
+    default: "Team"
+---
+# Report — {{date}}
+
+Prepared by: {{author}}
+
+## Highlights
+
+...
+```
+
+Frontmatter is not required. Templates without `params:` render as-is (no substitution).
+
+## Frontmatter params spec
+
+Each param entry in `params:` supports:
+
+| field | required | description |
+|-------|----------|-------------|
+| `name` | yes | placeholder name used as `{{name}}` in the body |
+| `type` | yes | `string` \| `number` \| `boolean` |
+| `default` | no | value applied when the param is omitted |
+
+Required params (no default) must be supplied by the caller of `RenderUserTemplate`. Missing required params produce an error at render time.
+
+## Size limit
+
+128 KB (UTF-8 encoded). Exceeding the limit returns `isError: true`.
+
+## Overwrite semantics
+
+By default (`overwrite: false`) writing to an existing file is an error.
+Pass `overwrite: true` to replace the file atomically.
+
+## When to use
+
+- You noticed a recurring structure (email skeleton, weekly report, issue template) — persist it for reuse.
+- The user asks you to create or update a template so they can render it later.
+- You want to encode a multi-step prompt skeleton with named slots.
+
+## Examples
+
+### Email template
+
+```js
+WriteUserTemplate({
+  name: "api-error-email",
+  content: `---
+description: Customer-facing API error notification email
+params:
+  - name: incident_id
+    type: string
+  - name: service
+    type: string
+  - name: eta
+    type: string
+    default: "unknown"
+---
+Dear Customer,
+
+We have detected an issue with **{{service}}** (incident {{incident_id}}).
+
+Our team is actively working on a resolution. Estimated resolution time: **{{eta}}**.
+
+We apologize for the inconvenience.
+
+— The Platform Team
+`
+})
+```
+
+### Report skeleton (no params)
+
+```js
+WriteUserTemplate({
+  name: "weekly-retro",
+  content: `# Weekly Retro
+
+## What went well
+-
+
+## What to improve
+-
+
+## Action items
+- [ ]
+`
+})
+```
+
+## Error cases
+
+| Situation | `isError` | message contains |
+|-----------|-----------|-----------------|
+| No authenticated user | true | "authenticated" |
+| `name` missing / empty | true | `"name"` |
+| `name` contains `/`, space, etc. | true | "alphanumeric" |
+| Content exceeds 128 KB | true | "bytes" |
+| File exists, `overwrite` not set | true | "overwrite" |
+
+## Notes
+
+- `WriteUserTemplate` is a META_TOOL — available in every movement without listing it in `allowed_tools`.
+- After writing, use `ReadUserTemplate` to verify the content and `RenderUserTemplate` to test substitution.
+- Use `ListUserAssets` to see all templates currently in the folder.