flow/catalogue

Source: 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

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

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

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

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

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.