# Workflows

A workflow is a reusable procedure Cora follows when you invoke it by name. Instead of re-explaining a multi-step process every time, you define it once and invoke it with a short prompt. Cora executes each step in order, substituting the specific details from your prompt.

<figure><img src="/files/QdTj453ZOqvwPdBOXys1" alt=""><figcaption></figcaption></figure>

***

### Storage locations

**Global workflows** available in every project:

```
~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/workflows/
```

**Project workflows** available in the current workspace only:

```
your-project/.cora/workflows/
```

Global workflows are good for personal processes that apply everywhere  PR prep, commit message generation, changelog updates. Project workflows are good for processes specific to a codebase the exact steps for adding a new feature given this project's structure.

***

### What goes in a workflow

Workflows are most useful for tasks that are multi-step, touch multiple files in a specific order, or need to be done consistently every time. Good candidates:

* Scaffolding a new feature: model, migration, service, route, tests, in the right order
* Preparing a pull request: lint, typecheck, test, write the description
* Adding a new database model: schema, migration, seed, typed repository class
* Creating a new background job: registration, queue config, retry logic, error handling

***

### Creating a workflow

Create a `.md` file in the workflows directory. Write steps as a numbered list with enough detail that Cora can execute each one without ambiguity.

**Example: `workflows/new-feature.md`**

```markdown
# New feature workflow

Run when adding a new backend feature. Replace [feature-name] with
the actual feature in each step.

1. Add the Prisma model to `prisma/schema.prisma`. Follow naming
   conventions in `.cora/rules/naming.md`.

2. Generate and apply the migration:
   `npx prisma migrate dev --name [feature-name]`

3. Update `prisma/seed.ts` if the new model needs local seed data.

4. Create a service at `src/services/[featureName].ts`. Export a
   class with typed methods. Define the interface at the top of
   the file.

5. Create a route at `src/routes/[feature-name].ts`. Validate all
   request bodies with Zod before reading any field from req.body.

6. Register the new route in `src/server.ts`.

7. Write integration tests in `tests/[featureName].test.ts`.
   Cover the happy path and at least two error cases.

8. Update `shared/types/index.ts` with any types shared between
   frontend and backend.
```

**Example: `workflows/pr-prep.md`**

```markdown
# PR preparation workflow

Run before opening a pull request.

1. Run `npm run lint` and fix all errors.
2. Run `npm run typecheck` and fix all type errors.
3. Run `npm test` — all tests must pass.
4. Check for changed files without test coverage and note them
   in the PR description.
5. Write the PR description: what changed, why, any breaking
   changes, how to test locally, and any follow-up work deferred.
6. Scan the diff for accidentally committed debug logging,
   commented-out code, or TODOs that should be filed as issues.
```

***

### Invoking a workflow

Reference the workflow by name in a prompt:

```
Run the new-feature workflow for a webhook subscription system.
```

```
Run pr-prep on the changes from this session.
```

Cora follows the steps in the workflow file, filling in the specific details from your prompt. If a step requires a decision the workflow doesn't cover, Cora asks before proceeding rather than guessing.

***

### Editing workflows directly

```bash
# Edit a global workflow
code ~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/workflows/pr-prep.md

# Edit a project workflow
code .cora/workflows/new-feature.md
```

Workflow steps can reference other config files pointing at `rules/naming.md` or `skills/api-conventions.md` for the specifics. This keeps workflows short and avoids duplicating content.


---

# 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://docs.codemate.ai/cora/configuration/workflows.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.