Puffin Ship Docs

workspace_analyze

AI summary of all project files (file descriptions and overall topics), stored as shared context for later steps.

When to use

Include as the first step in every pipeline that uses ai_agent, even single-file projects. Wire it as an input: entry in the ai_agent step; the processor will pre-inject its output into the agent's context block as a === WORKSPACE ANALYSIS === section. Without it, the agent has no content summaries, topics, or key moments for your files.

Also useful standalone for understanding what's in a new project folder.

In the editor

Add it from the Library (Transcript group), or with + add step and a search for workspace_analyze, and move it to the top of the pipeline with the ↑ control.

There is nothing to fill in. The step has no parameters, and it finds the workspace's files by itself, so the Inspector shows only the step ID.

To let an AI step use what it found, select that step, add an entry under Inputs, give it an id such as analysis, choose step, and pick this step from the dropdown. The AI step then starts knowing what every file in the workspace contains, instead of starting blank.

Nothing lands on the timeline. This step produces reading material for later steps, so in the run view it simply reports done, and its effect shows up in the quality of the steps that follow it.

YAML Example

- id: analyze_workspace
  processor: workspace_analyze
  cache: true

Inputs

None. Scans all files in the workspace automatically.

Params

This processor has no configurable parameters.

Output

Analysis containing descriptions of all discovered project files.

Notes

  • Uses Puffin Ship's built-in AI: no API key required.
  • Always use cache: true: the workspace doesn't change between runs.
  • Wire as an input: entry in your ai_agent step: {id: analysis, step: analyze_workspace}. The agent receives it pre-injected in the context block, so no tool call is needed.