# Builder Patterns

## What this is

This page describes common Protege patterns and when to use each one.

## When to use it

Use this page before writing a Builder prompt or when you are deciding whether a workflow should be event-driven, scheduled, or chat-assisted.

## Patterns

### Event-driven Protege

Use this when an external app event should start the workflow.

Examples:

* A GitHub pull request opens
* A Linear issue changes priority
* An Asana task receives a new comment
* A Slack message arrives in a monitored channel

Event-driven Proteges need Trigger Access for the source and Tool Access for any resulting action.

### Scheduled Protege

Use this when Hookshot™ should run on a recurring schedule.

Examples:

* Send a weekday summary
* Check stale work items every morning
* Produce a weekly status update

Scheduled Proteges need at least one enabled schedule. If the Protege only runs on schedules, setup will block publishing until a schedule exists.

### Chat-assisted Protege

Use this when a connected chat surface should route conversation into Hookshot.

Examples:

* Receive a Slack message and decide whether to reply
* Watch an Asana project or portfolio for comments that need follow-up

Chat-assisted Proteges should stay narrowly scoped to the channels, projects, portfolios, or teams that should be monitored.

### Tool-writing Protege

Use this when the Protege should create or update information in another app.

Examples:

* Create a Linear issue
* Post a Slack message
* Update an Asana task
* Comment on a GitHub item

Tool-writing Proteges require careful Tool Access review because they can change external systems.

### Review-first Protege

Use this when you want to draft and inspect the workflow before enabling it.

This is the safest first path for workflows with new integrations, new teams, or uncertain scope.

## How to choose

Use an event-driven pattern when the workflow starts from live app activity.

Use a scheduled pattern when the workflow starts from time.

Use a chat-assisted pattern when conversation is the main source.

Use a review-first pattern when the workflow is new, risky, or still being shaped.

{% hint style="info" %}
Many production Proteges combine patterns. For example, a Protege can be event-driven and tool-writing, or scheduled and tool-writing. The important part is making the trigger and allowed actions explicit.
{% endhint %}

## How to verify

You chose the right pattern when you can answer:

* What starts the Protege?
* What apps does it need to read from?
* What apps can it write to?
* What is the smallest safe scope?
* Where will you confirm the result?

## Common failures

* Treating a scheduled workflow like an event-driven workflow
* Giving a tool-writing Protege broader access than it needs
* Monitoring a whole workspace when one team, repo, project, or channel would work
* Publishing before the trigger or schedule is ready

## Next step

* [Create a Protege](/create-a-protege.md)
* [Skills Hub](/create-a-protege/skills-hub.md)
* [Chat](/create-a-protege/chat.md)
* [Readiness and blockers](/create-a-protege/readiness-and-blockers.md)
* [Safe rollout](/event-feed/safe-rollout.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.tryprotege.com/create-a-protege/builder-patterns.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.