Workflows

Markdown files that define step-by-step processes for recurring tasks.

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.

---

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

# 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

# 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

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