pipelines.md

Repo Workflow Assets

The platform core is thread/job/run/worktree based, but projects can also carry repo-local workflow assets that define prompts, gates, and execution templates for scaffolded repos.

These files live inside the target repository, not the Esperta Code service repo.

Asset Layout

Path	Purpose
.esperta-code/config.yml	Repo-local agent defaults, specs settings, gates, and hooks
.esperta-code/pipeline.yml	Ordered execution steps for repo-local workflows
.esperta-code/prompts/	Prompt templates referenced by repo config or pipeline steps
WORKFLOW.md	Main execution prompt scaffolded for new projects

Generated by project add

esperta-code project add can scaffold these files when a repository does not already have them.

Example .esperta-code/config.yml

agent:
  adapter: codex
  approval_policy: auto
  timeout_ms: 600000
  max_turns: 20

specs:
  enabled: true
  directory: specs

gates:
  test_command: bun test
  lint_command: bun run lint

Example .esperta-code/pipeline.yml

phases:
  - name: execute
    steps:
      - name: run
        agent: codex
        prompt: WORKFLOW.md
        success:
          command: "bun test && bun run lint"
      - name: create_pr
        agent: codex
        prompt: .esperta-code/prompts/publish.md

What the Pipeline File Controls

• step ordering
• per-step agent choice
• success conditions
• optional retry behavior
• prompt template selection

All repo-local pipeline steps still execute inside the worktree prepared for the run.