<!-- Generated by scripts/gen-docs.ts from the TSDoc in src/. Do not edit by hand. -->

# `flow/catalogue`

Source: [`src/flow/catalogue.ts`](https://github.com/AI-for-dev/combo/blob/main/src/flow/catalogue.ts)

What a flow is checked against, and where it is found on disk.

Flows and agents are looked for where every definition is: the package's
own, the user's `~/.pi/agent/`, the repository's `.pi/`, least specific
first, and whoever is closer to the work wins the name.

Unlike `loadAgents`, the agents' side keeps the files that are not agents,
with their cause. A flow names its agents and is checked before it runs, so
a name matching a broken file is reported as that file being broken, never
as unknown. And a broken file wins its name like any other: a repository's
`scout.md` that stopped parsing is not quietly replaced by the user's.

The `pipelines/` directories the linear format was kept in are read too,
and only to be refused: see {@link removedPipelines}.

## `FlowCatalogue`

*type*

```typescript
export type FlowCatalogue = {
	/** Flow files, found by their file name without `.md`, which is the flow's name. */
	readonly flows: readonly FoundFlow[];
	/** The agents that parsed, one per name, the nearest winning it. */
	readonly agents: readonly Agent[];
	/** Agent files that are not agents, each under the name it would be asked for. */
	readonly brokenAgents: readonly BrokenAgent[];
	/** The directory the catalogue was loaded for: an agent's skills are looked up from it. */
	readonly cwd: string;
};
```

What a flow is checked against: the flow files by name, and the agents.

## `FoundFlow`

*type*

```typescript
export type FoundFlow = MarkdownFile & {
	/** The directory it was read from: the package's, the user's or the repository's. */
	readonly source: AgentSource;
};
```

A flow file, and whose it is: the package's, the user's or the repository's.

## `loadFlowCatalogue`

*function*

```typescript
export function loadFlowCatalogue(options: { cwd?: string; scope?: AgentScope; builtin?: boolean } = {}): FlowCatalogue { /* … */ }
```

The flows and agents of `cwd`, read from disk on every call, so editing a
file is enough.

The scope defaults to `"user"` and `builtin` is off, as for `loadAgents`: a
repository's flows and agents are third-party instructions.

## `RemovedPipeline`

*type*

```typescript
export type RemovedPipeline = {
	/** Its file name without `.md`, the flow's name it would have had. */
	readonly name: string;
	/** Whose directory it is in: the user's or the repository's. */
	readonly source: AgentSource;
	/** Its `pipeline-format-removed` fault. */
	readonly fault: Fault;
};
```

A file left in an old `pipelines/` directory: its name, whose it is, and why nothing reads it.

## `removedPipelines`

*function*

```typescript
export function removedPipelines(options: { cwd?: string; scope?: AgentScope } = {}): RemovedPipeline[] { /* … */ }
```

Every file in the user's or the repository's `pipelines/`, each refused
with `pipeline-format-removed`, on the same scope as
{@link loadFlowCatalogue}.

Nothing is loaded from them. They are read so that a `build.md` of your own
left in `.pi/pipelines/` is named, rather than shadowed in silence by the
shipped `build` flow. The package ships no `pipelines/` of its own.