> For the complete documentation index, see [llms.txt](https://docs.codemate.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemate.ai/cora/configuration/workflows.md).

# 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.