| name | respond-and-organize |
| description | Write product-facing replies and organize run outputs in the canonical Formtastic artifact layout. Always applies to every turn because reply.md is the visible chat response and all structured output depends on the run directory contract. |
Respond and organize
When to use this
Use this on every Formtastic agent turn. It is the baseline response and
artifact-organization contract.
How to do it
- Write the visible answer to
$FORMTASTIC_RUN_DIR/output/reply.md.
- Keep the reply product-facing: summarize what you did or found, what is
ready for review, and any real limitation or blocker.
- Do not expose harness details in the visible reply: no raw output paths,
validator package details, run directory internals, or "I wrote JSON" unless
the user explicitly asks for audit/debug details.
- Never claim a card, replacement, finding, issue, or source bundle is ready
unless the corresponding artifact exists and validates.
- When the current form is empty and you produce a valid
proposed-questionnaire.json, the host auto-applies that first draft. Say the
initial form/micro starter has been created and is ready to review; do not ask
the user to click Apply or Replace.
Artifact map
All writes go under $FORMTASTIC_RUN_DIR/output/:
| User intent | Artifact |
|---|
| Reply only | reply.md |
| Small form edits | suggestions.json plus reply.md |
| Broad replacement | proposed-questionnaire.json plus reply.md |
| Evidence/research | research/bundle.json, supporting research/** files, findings.json, plus reply.md |
| Critique/validation | issues.json plus reply.md |
If a turn produces multiple artifacts, create and validate the structured
artifacts first, then write the final reply.md to reflect what actually
landed.
Good reply shape
Use concise Markdown:
- Lead with the outcome.
- Mention the key clinical/product rationale.
- Say what is ready for review only when the artifact is valid.
- State blockers plainly if the artifact could not be produced.
Common mistakes
- Saying "see
output/suggestions.json" instead of "review the suggestion
cards".
- Saying "sources are saved" when only
findings.json exists.
- Hiding validation failures behind a success-shaped reply.
- Writing to
output/... relative to the form cwd instead of
$FORMTASTIC_RUN_DIR/output/....
