Clearly Quickstart

Clearly Quickstart is a private repository for authoring review template YAML outside the Clearly AI web app.

Use it when you want to manage review templates as code, edit in Cursor or another coding assistant, and upload finished YAML into Clearly AI.

Ask your Clearly AI contact for repository access before following the steps below.

What is in the repo

The repo includes:

• questionnaires/schema-questionnaire-v1.json: JSON Schema for review template YAML.
• questionnaires/questionnaire-blocks-reference.yaml: commented examples of supported block types.
• questionnaires/stride-tm.yaml: a working STRIDE threat model example.
• .agents/commands/create-questionnaire.md: instructions for AI-assisted review template authoring.
• questionnaires/tests/test_questionnaires.py: tests that validate review template files.

Repository: Clearly-AI/clearly-quickstart (private)

Create a review template

1. Ask Clearly AI for access to the private quickstart repo.
2. Clone the repo after access is granted.
3. Open it in Cursor or your editor.
4. Start from questionnaires/stride-tm.yaml or questionnaires/questionnaire-blocks-reference.yaml.
5. Save your new review template under questionnaires/.
6. Validate it before upload.

uv run pytest

Then upload the YAML in Clearly AI from Review Templates > Upload Review Template.

Author with an AI assistant

The repo includes .agents/commands/create-questionnaire.md. Use it as the instruction file when asking an AI coding assistant to create or revise a review template.

Good input looks like this:

Create a review template that classifies a project by production exposure, internet exposure,
personal data handling, authentication model, and required follow-up review.
Use single-select fields where the output should drive workflow branching.
Use freeform fields only for evidence summaries.

After generation:

1. Review the YAML yourself.
2. Run uv run pytest.
3. Upload the file to Clearly AI.
4. Run a test review against a project with representative sources.

What to include

Every review template needs:

metadata:
  title: "Review template title"
  description: "What this review is for"

blocks:
  - text: "## Section"
  - prompt: "Question the AI should answer."

Use:

• text for headings and reviewer guidance.
• prompt for freeform answers.
• options for single-select answers.
• multi_options for multi-select answers.
• hidden_instructions when the answering engine needs private guidance.
• assert_any, assert_all, or assert_fuzzy when you want pass/fail status.
• aggregate_risks when option-level risk scores should roll up.
• summarize as the final block when you need a generated summary.

See Review template schema for field details.

Upload and versioning

The uploaded filename becomes the review template identifier. Uploading a file with the same identifier creates a new version. Existing reviews keep the review template version they were run with.

To fork a review template, change the filename before upload.

Common mistakes

YAML turns NO into false. Quote values such as "NO".

The summary block is not last. Move summarize to the end. A review template can have at most one.

The model guesses. Tighten the prompt, add hidden instructions, or add better project sources and Knowledge Base context.

A workflow needs structured branching. Use single-select or multi-select questions instead of freeform prompts.