vinta-ai-workflows 0.7.0-alpha8 → 0.7.0

package/schemas/interview-round.v1.schema.json

@@ -0,0 +1,346 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/interview-round.v1.schema.json",
+  "title": "interview round (v1)",
+  "description": "One round of an agent-driven interview, written by the agent to `<interview-dir>/rounds/round-NN.json` and rendered by the `vinta-ai-maestro` interview page as a full-screen decision form. Decisions are grouped; each decision carries the context the agent already knows, an optional explainer document (Markdown with Mermaid, or HTML), and options with their consequences. The browser answers with an `interview-answers.v1` payload. Lives at `<interview-dir>/rounds/round-NN.json`, where `<interview-dir>` is `.vinta-ai-workflows/interviews/<slug>/` in a target project (gitignored). Written by the agent running the interview; served to the browser by `vinta-ai-maestro interview`. GENERATED from packages/vinta-ai-maestro/src/interview/document.ts — edit there, not here. See schemas/README.md for versioning rules.",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "type": "number",
+      "const": 1
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "1-based round number. Must match the `NN` in the filename (`round-01.json` → 1)."
+    },
+    "interview": {
+      "type": "object",
+      "properties": {
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "Stable kebab-case id for the whole interview. The page keys browser drafts on it; the agent uses it as the interview directory name."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human title shown in the header, e.g. `Order tags — spec interview`."
+        },
+        "skill": {
+          "description": "Skill that is running the interview (`create-spec`, `plan-feature`, …). Display only.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "slug",
+        "title"
+      ],
+      "additionalProperties": false
+    },
+    "kind": {
+      "default": "questions",
+      "description": "`questions` (default) renders decisions one per screen. `readback` additionally renders `summary` first — use it for the final \"anything I got wrong before I draft?\" round.",
+      "type": "string",
+      "enum": [
+        "questions",
+        "readback"
+      ]
+    },
+    "intro": {
+      "description": "Markdown shown above the first decision — what this round is about, what changed since the last one.",
+      "type": "string"
+    },
+    "summary": {
+      "description": "Markdown read-back of every load-bearing decision so far. Rendered only when `kind` is `readback`.",
+      "type": "string"
+    },
+    "replies": {
+      "description": "Agent answers to questions the user asked in earlier rounds (`interview-answers.v1` → `questions[]`). Shown next to the decision they refer to, or in the general panel when `decision_id` is absent.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/reply"
+      }
+    },
+    "groups": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/group"
+      },
+      "description": "Ordered groups (the left rail). For `create-spec` these are its interview groups A–I."
+    }
+  },
+  "required": [
+    "schema_version",
+    "round",
+    "interview",
+    "groups"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "reply": {
+      "type": "object",
+      "properties": {
+        "question_id": {
+          "description": "`questions[].id` from the answers payload being replied to.",
+          "type": "string"
+        },
+        "decision_id": {
+          "description": "Decision the question was about. Omit for general questions.",
+          "type": "string"
+        },
+        "question": {
+          "type": "string",
+          "description": "The user's question, quoted."
+        },
+        "answer": {
+          "type": "string",
+          "description": "Markdown answer. Mermaid fences allowed."
+        }
+      },
+      "required": [
+        "question",
+        "answer"
+      ],
+      "additionalProperties": false
+    },
+    "group": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "decisions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/decision"
+          }
+        }
+      },
+      "required": [
+        "id",
+        "title",
+        "decisions"
+      ],
+      "additionalProperties": false
+    },
+    "decision": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable id within the interview (e.g. `D4`). Reused across rounds when a decision is re-asked."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The question, as a full sentence the user can answer."
+        },
+        "short": {
+          "description": "Rail label when `title` is long.",
+          "type": "string"
+        },
+        "why": {
+          "description": "One sentence on why the answer matters (the `*Why:*` line from the create-spec question bank).",
+          "type": "string"
+        },
+        "context": {
+          "description": "Markdown: what the agent already knows that bears on this decision — earlier answers quoted back, repo facts, constraints. Mermaid fences allowed.",
+          "type": "string"
+        },
+        "explainer": {
+          "description": "Rich explanation. Either inline Markdown (string or `{markdown}`) or a file under `<interview-dir>/docs/` (`{path}`). `.md` files render in the page with Mermaid support; `.html` files render in a sandboxed iframe for layouts Markdown cannot express.",
+          "$ref": "#/$defs/explainer"
+        },
+        "required": {
+          "default": true,
+          "description": "When `false`, the round can be submitted with this decision left open. Default `true`.",
+          "type": "boolean"
+        },
+        "waivable": {
+          "default": true,
+          "description": "Show the \"not applicable — skip\" toggle. Default `true`.",
+          "type": "boolean"
+        },
+        "waive_label": {
+          "type": "string"
+        },
+        "input": {
+          "$ref": "#/$defs/input"
+        }
+      },
+      "required": [
+        "id",
+        "title",
+        "input"
+      ],
+      "additionalProperties": false
+    },
+    "explainer": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Inline Markdown. Mermaid fences allowed."
+        },
+        {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string"
+            },
+            "markdown": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Inline Markdown. Mermaid fences allowed."
+            }
+          },
+          "required": [
+            "markdown"
+          ],
+          "additionalProperties": false,
+          "description": "Inline Markdown with a title."
+        },
+        {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "pattern": "^(docs\\/)?[^\\0]+\\.(md|markdown|html|htm)$",
+              "description": "Relative to the interview dir, inside `docs/` (e.g. `docs/D4-concurrency.md`). The server refuses anything that escapes `docs/`."
+            }
+          },
+          "required": [
+            "path"
+          ],
+          "additionalProperties": false,
+          "description": "A document under `docs/`. `.md` files render in the page with Mermaid support; `.html` files render in a sandboxed iframe, for layouts Markdown cannot express."
+        }
+      ]
+    },
+    "input": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "single",
+            "multi",
+            "text",
+            "confirm"
+          ],
+          "description": "`single` — pick one option; `multi` — pick any; `text` — free-form answer; `confirm` — like `single`, for yes/no and read-back confirmations."
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        },
+        "allow_other": {
+          "description": "Adds a \"Something else\" card with a text field. Default: on when `options` is empty, off otherwise.",
+          "type": "boolean"
+        },
+        "other_label": {
+          "type": "string"
+        },
+        "other_placeholder": {
+          "type": "string"
+        },
+        "label": {
+          "description": "`text` input only — field label.",
+          "type": "string"
+        },
+        "placeholder": {
+          "description": "`text` input only — placeholder with a real example answer.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false
+    },
+    "option": {
+      "type": "object",
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable machine value echoed back in `answers[].values`."
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short card title, a few words."
+        },
+        "description": {
+          "description": "One or two sentences: what this option is.",
+          "type": "string"
+        },
+        "consequences": {
+          "description": "What picking this implies downstream — a new plan phase, a one-way door, a dependency, a cost. The \"choose wisely\" line.",
+          "type": "string"
+        },
+        "recommended": {
+          "description": "Marks the agent's recommended default. At most one per decision.",
+          "type": "boolean"
+        },
+        "tags": {
+          "description": "Small pills under the card, e.g. `{label: \"One-way door\", tone: \"warn\"}`.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/tag"
+          }
+        },
+        "explainer": {
+          "description": "Rich explanation. Either inline Markdown (string or `{markdown}`) or a file under `<interview-dir>/docs/` (`{path}`). `.md` files render in the page with Mermaid support; `.html` files render in a sandboxed iframe for layouts Markdown cannot express.",
+          "$ref": "#/$defs/explainer"
+        }
+      },
+      "required": [
+        "value",
+        "label"
+      ],
+      "additionalProperties": false
+    },
+    "tag": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "string"
+            },
+            "tone": {
+              "type": "string",
+              "enum": [
+                "neutral",
+                "warn",
+                "ok"
+              ]
+            }
+          },
+          "required": [
+            "label"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/schemas/plan-review.v1.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vintasoftware/vinta-ai-workflows/schemas/plan-review.v1.schema.json",
+  "title": "vinta-ai-maestro plan review",
+  "description": "A plan review: comments on a plan-feature plan and the conversation about it between the person reviewing it and the agent that wrote it. Lives at `ai-plans/<workflow-id>.review.json` in a target project, beside the plan and its `.workflow.json`, and is committed with them. Written by the `vinta-ai-maestro` review page and by `vinta-ai-maestro review reply`; read by the agent running `plan-feature` through `vinta-ai-maestro review wait`. GENERATED from packages/vinta-ai-maestro/src/review/document.ts — edit there, not here. See schemas/README.md for versioning rules.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "number",
+      "const": 1
+    },
+    "workflow_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "open",
+        "approved"
+      ]
+    },
+    "approved_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "comments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "anchor": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "plan"
+                  }
+                },
+                "required": [
+                  "kind"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "section"
+                  },
+                  "section": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "heading": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 300
+                  }
+                },
+                "required": [
+                  "kind",
+                  "section"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "phase"
+                  },
+                  "node": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  }
+                },
+                "required": [
+                  "kind",
+                  "node"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "prompt"
+                  },
+                  "node": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "role": {
+                    "type": "string",
+                    "enum": [
+                      "implementer",
+                      "fixer"
+                    ]
+                  }
+                },
+                "required": [
+                  "kind",
+                  "node",
+                  "role"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "const": "gate"
+                  },
+                  "gate": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "node": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  }
+                },
+                "required": [
+                  "kind",
+                  "gate"
+                ],
+                "additionalProperties": false
+              }
+            ]
+          },
+          "quote": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "author": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "human",
+                  "agent"
+                ]
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              }
+            },
+            "required": [
+              "kind"
+            ],
+            "additionalProperties": false
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8000
+          },
+          "created_at": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "open",
+              "resolved"
+            ]
+          },
+          "resolved_at": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sent_at": {
+            "type": "string",
+            "minLength": 1
+          },
+          "replies": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "author": {
+                  "type": "object",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "human",
+                        "agent"
+                      ]
+                    },
+                    "name": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 200
+                    }
+                  },
+                  "required": [
+                    "kind"
+                  ],
+                  "additionalProperties": false
+                },
+                "body": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 8000
+                },
+                "created_at": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "sent_at": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "id",
+                "author",
+                "body",
+                "created_at"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "anchor",
+          "author",
+          "body",
+          "created_at",
+          "status",
+          "replies"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "conversation": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "message",
+              "approval"
+            ]
+          },
+          "author": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "human",
+                  "agent"
+                ]
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              }
+            },
+            "required": [
+              "kind"
+            ],
+            "additionalProperties": false
+          },
+          "body": {
+            "type": "string",
+            "maxLength": 8000
+          },
+          "created_at": {
+            "type": "string",
+            "minLength": 1
+          },
+          "comment_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "delivered_at": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "id",
+          "kind",
+          "author",
+          "body",
+          "created_at"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "schema_version",
+    "workflow_id",
+    "status",
+    "comments",
+    "conversation"
+  ],
+  "additionalProperties": false
+}